Webhooks: criar e testar
Mande vendas, comissões, pagamentos, cadastros e envios para o seu ERP, CRM ou automação (n8n, Make, Zapier) no momento em que acontecem.
Um webhook avisa outro sistema (ERP, CRM, planilha, n8n, Make, Zapier) toda vez que algo acontece no programa: uma venda atribuída, uma comissão aprovada, um pagamento concluído, um kit enviado. A plataforma manda um POST em JSON para a URL que você cadastrar, assinado com um segredo.
Passo a passo#
- Abra Configurações › Webhooks e clique em Novo webhook.
- Em URL do endpoint, cole o endereço que vai receber os eventos. Ele precisa ser https e responder com status 2xx em até 10 segundos.
- Em Nome (opcional), dê um nome para reconhecer depois (ex.: ERP, CRM, n8n).
- Em Eventos enviados, marque os eventos que esse endereço deve receber. Marcar o grupo marca todos os eventos dele; Marcar todos marca os 39.
- Clique em Criar webhook. Você vai para a página do webhook com o Segredo de assinatura já revelado.
- Copie o segredo e guarde no seu servidor como variável de ambiente (nunca no front-end).
- Em Testar, escolha um evento e clique em Enviar teste.
A lista de eventos e o formato de cada um ficam em Eventos, payload e assinatura. Cada marca pode ter até 10 webhooks.
A página do webhook#
- Endpoint: a URL, quando foi criado, a Última entrega aceita e as Falhas seguidas.
- Segredo de assinatura: o olho revela, o ícone de copiar copia. Trocar segredo gera um novo e o atual para de valer na próxima entrega: atualize o seu servidor logo em seguida.
- Eventos: os eventos inscritos. Editar URL e eventos muda os dois.
- Testar: manda um exemplo com dados fictícios e
test: true. Owebhook.pingsó confere a conexão. - Entregas: o histórico dos últimos 30 dias, com filtros Todas, Com falha, Na fila e Entregues. Clique numa entrega para ver o Corpo enviado, a Resposta do seu servidor e cada tentativa. Reenviar manda de novo.
No topo ficam Pausar (ou Retomar / Reativar) e Excluir.
O que cada status significa#
| Status do webhook | Significado |
|---|---|
| Ativo | Recebendo eventos. |
| Pausado | Você pausou. Nenhum evento é gerado para ele enquanto estiver pausado, e nada fica acumulado para depois. |
| Desligado | A plataforma desligou porque o endereço falhou por mais de 3 dias seguidos. A equipe recebe a notificação "Webhook desligado". |
| Status da entrega | Significado |
|---|---|
| Entregue | Seu servidor respondeu 2xx. |
| Na fila / Enviando | Ainda vai sair ou está saindo agora. |
| Tentando de novo | Falhou e tem um reenvio agendado. A entrega mostra a Próxima tentativa. |
| Falhou | Acabaram as tentativas automáticas. Dá para Reenviar manualmente. |
| Cancelado | A entrega não saiu porque o webhook foi pausado ou desligado. |
Erros comuns e o que fazer#
| Mensagem | Por quê | O que fazer |
|---|---|---|
| "Use uma URL https:// (o Hub não envia dados por conexão sem criptografia)." | A URL começa com http://. | Use o endereço https. |
| "Use um endereço público na internet." | A URL aponta para um endereço interno ou local. | Use um endereço acessível pela internet. |
| "Escolha ao menos um evento para enviar." | Nenhum evento marcado. | Marque pelo menos um evento. |
| "Limite de 10 webhooks por marca. Exclua um que não usa mais." | Você já tem 10 webhooks. | Exclua um que não usa, ou junte eventos num só endereço. |
| "Resposta HTTP 500" (ou outro código) | Seu servidor respondeu com erro. | Veja a Resposta do seu servidor na entrega e corrija do seu lado. |
| "Sem resposta em 10 s" | Seu servidor demorou demais. | Responda 2xx logo e processe o evento depois. |
| "Redirecionamento (301) não é seguido: cadastre a URL final." | A URL redireciona para outra. | Cadastre o endereço final. |
| "Reative o webhook antes de testar." | O webhook está Desligado. | Corrija o servidor e clique em Reativar. |
| "Somente o dono da marca pode configurar webhooks." | Você entrou como equipe. | Peça ao dono da marca. |
Perguntas frequentes#
Meu webhook foi desligado. Como volto a receber?
Abra o webhook, veja o Último erro e as respostas nas Entregas, corrija o seu servidor e clique em Reativar. Depois mande um teste. As entregas canceladas no desligamento não são reenviadas sozinhas: use Reenviar nas que precisar.
Posso mandar os mesmos eventos para dois sistemas?
Pode. Crie um webhook para cada endereço e marque os mesmos eventos nos dois.
Recebi o mesmo evento duas vezes. É erro?
Pode acontecer num reenvio. Use o id do evento para não processar o mesmo evento duas vezes.

