Um webhook do WooCommerce é uma mensagem que a sua loja envia para outro serviço quando algo acontece, como um pedido criado ou atualizado. Você o configura uma vez em WooCommerce, Configurações, Avançado, Webhooks: escolhe o evento (o tópico), o endereço para onde ele vai (a URL de entrega) e um segredo usado para assinar cada mensagem. A partir daí, o WooCommerce entrega o pedido nesse endereço toda vez que o evento acontece. A maioria dos problemas vem de quatro lugares: o tópico errado, um segredo diferente de cada lado, um webhook sem usuário com permissão para ler pedidos e entregas pausadas ou atrasadas.
Este guia explica cada campo em palavras simples e depois passa por esses erros.
O que é um webhook, na linguagem da loja
Pense nele como um e-mail automático entre dois sistemas. Em vez de uma pessoa conferir os seus pedidos e copiá-los para algum lugar, o WooCommerce envia cada pedido para um serviço no momento em que ele muda. O serviço pode ser uma ferramenta de contabilidade, um parceiro de logística ou um widget de notificações de vendas.
Duas coisas tornam isso melhor do que copiar dados à mão ou por uma exportação noturna:
- É imediato. O serviço que recebe fica sabendo do pedido em instantes.
- Pode ser conferido. Com um segredo, quem recebe consegue provar que a mensagem veio da sua loja e não foi alterada no caminho.
Os campos da tela de webhook
| Campo |
O que significa |
O que colocar |
| Nome |
Uma identificação para você |
Algo que diga para onde vai, como "Pedidos para a Provedly" |
| Status |
Ativo, Pausado ou Desativado |
Ativo, quando você estiver pronto |
| Tópico |
Qual evento dispara uma entrega |
Normalmente um tópico de pedido, veja abaixo |
| URL de entrega |
Para onde o WooCommerce envia a mensagem |
O endereço que o serviço que recebe fornece, começando com https |
| Segredo |
Um valor compartilhado usado para assinar cada mensagem |
Um valor longo que você também cola no serviço que recebe |
| Versão da API |
O formato da mensagem |
A versão atual da WP REST API, a menos que o serviço diga outra coisa |
Há uma configuração que não aparece como campo, mas que importa muito: todo webhook pertence a um usuário do WordPress. O WooCommerce monta cada entrega lendo o pedido pela própria API REST como esse usuário. Se o usuário não pode ler pedidos, a entrega leva um erro em vez do pedido.
order.created ou order.updated
É nesses dois tópicos que a maioria das configurações dá errado.
- order.created dispara uma vez, quando o pedido é salvo pela primeira vez. Em muitas formas de pagamento isso acontece antes de o cliente pagar, então o pedido ainda pode estar em Pagamento pendente.
- order.updated dispara toda vez que o pedido muda: quando o pagamento é aprovado e o status passa para Processando, quando você o marca como Concluído, quando você adiciona uma nota.
Se você quer agir só sobre pedidos pagos, order.created sozinho pode perder o momento do pagamento, e pode entregar pedidos que nunca são pagos. order.updated vê o pagamento, mas também envia o mesmo pedido várias vezes. A resposta habitual é escutar order.updated e fazer o serviço que recebe cuidar de duas coisas: ignorar pedidos cujo status não seja pago e lembrar quais ids de pedido já tratou.
É exatamente isso que a Provedly faz com o WooCommerce. Ela registra um pedido só quando o status é Processando ou Concluído, e registra cada id de pedido uma vez, não importa quantas atualizações cheguem. Ela também aceita entregas de order.created, com as mesmas regras.
O segredo e a assinatura
Quando um webhook tem um segredo, o WooCommerce passa o corpo da mensagem e o segredo por uma função de hash (HMAC-SHA256) e envia o resultado num cabeçalho chamado X-WC-Webhook-Signature. O serviço que recebe faz o mesmo cálculo com a cópia dele do segredo. Se os dois resultados batem, a mensagem veio de alguém que conhece o segredo e não foi alterada no caminho. Se diferem, o serviço deve descartar a mensagem.
Pontos práticos:
- O segredo precisa ser idêntico dos dois lados, incluindo maiúsculas e sem espaços extras.
- Escolha um valor longo e aleatório, e mantenha-o fora de capturas de tela e chamados de suporte.
- Mudá-lo de um lado quebra as entregas até você mudá-lo do outro.
A assinatura é o que permite que uma notificação de vendas diga com honestidade "Compra verificada". Sem ela, qualquer um que descobrisse a URL de entrega poderia enviar um pedido inventado. Nosso texto sobre segredos de assinatura de webhook compara como Stripe, Shopify e WooCommerce fazem isso.
Erros comuns e correções
| O que você vê |
Causa |
Correção |
| O serviço que recebe ganha um erro da API REST em vez do pedido, muitas vezes sobre permissões |
O usuário do webhook não pode ler pedidos, ou o webhook foi criado por um script sem usuário |
Garanta que um administrador seja o dono do webhook. O plugin da Provedly atribui um quando cria o webhook |
| "Invalid signature" no registro de entregas |
Os segredos são diferentes |
Cole o mesmo segredo dos dois lados |
| Nada chega |
O webhook está Pausado ou Desativado, ou a URL de entrega tem um erro de digitação |
Mude para Ativo e copie a URL de novo |
| O webhook mudou sozinho para Desativado |
O WooCommerce desativa um webhook depois de falhas repetidas na entrega |
Corrija a causa e depois volte para Ativo |
| Os pedidos chegam minutos atrasados |
As entregas entram numa fila de tarefas em segundo plano, que rodam quando o site recebe visitas ou por uma tarefa agendada |
Confira em WooCommerce, Status, Ações agendadas se há tarefas de webhook pendentes |
| Pedidos não pagos aparecem em outra ferramenta |
O tópico é order.created e a ferramenta não confere o status |
Use order.updated e filtre por status |
O WooCommerce mantém um registro das entregas em WooCommerce, Status, Logs. Ele mostra a resposta que o serviço que recebe devolveu, o que normalmente é o jeito mais rápido de ver o que deu errado.
Quando você cria um webhook novo, o WooCommerce envia um "ping" curto de teste para a URL de entrega. Um receptor bem construído responde a ele para que o webhook possa ser ativado; esse ping não contém pedido.
Como fazer isso com a Provedly
Você não precisa configurar nada disso à mão. O plugin gratuito da Provedly cria o webhook quando você cola a URL de entrega e o segredo na página de configurações dele e clica em Save: tópico order.updated, versão atual da API, ativo, assinado com o seu segredo, com um administrador como dono. Nosso guia de notificações de vendas recentes no WooCommerce mostra a configuração passo a passo.
Perguntas frequentes
Preciso de um segredo no meu webhook do WooCommerce?
Não para o WooCommerce enviá-lo, mas você sempre deve definir um quando o receptor oferece suporte. Sem ele, o receptor não consegue distinguir as mensagens da sua loja das de qualquer outra pessoa, e uma notificação de vendas feita com mensagens não assinadas não pode ser chamada de verificada com honestidade.
Posso ter mais de um webhook para pedidos?
Sim. Cada serviço recebe o próprio webhook, com URL de entrega e segredo próprios. Eles não interferem um no outro, e pausar um deixa os outros rodando.
Um webhook novo envia os meus pedidos antigos?
Não. Um webhook dispara com eventos que acontecem depois que ele existe, então pedidos antigos só são enviados se mudarem, por exemplo quando você marca um como Concluído. Para trazer o histórico, use a opção de importação do serviço que recebe.
Conecte os seus pedidos do WooCommerce por um webhook assinado no plano gratuito da Provedly criando uma conta.