Webhook desativado
5 entregas falhas desativam o webhook. Como voltar a receber.
Depois de 5 entregas falhas, o webhook inteiro é desativado, não só o evento. A entrega para de vez, para todos os eventos seguintes, até você religá-lo.
O que conta como sucesso
| Resultado | Entrega |
|---|---|
Qualquer 2xx: 200, 201, 202, 204 | Sucesso |
3xx, 4xx, 5xx | Falha |
| Timeout de 15 s | Falha |
| Erro de conexão, DNS ou TLS | Falha |
202 Acceptedé sucesso, e é a resposta recomendada para quem recebe o evento e enfileira o processamento.
A escada da desativação
| Etapa | O que acontece |
|---|---|
| Entregas 1 a 4 falham | O evento volta para a fila e é retentado no ciclo seguinte, cerca de 2 s depois |
| 5ª falha | O evento é marcado como erro e o webhook é desativado |
| Depois | Nenhum evento novo é entregue até você religar |
É uma tentativa por ciclo, não várias seguidas, para que um destino lento não segure a fila dos outros. A desativação não é por evento: é o cadastro do webhook que é desligado.
Quem recebe o aviso
O e-mail de desativação vai para o e-mail do responsável cadastrado no webhook e para o e-mail de quem assina a conta BeeFood. Ele traz o endereço cadastrado e o último erro recebido.
São dois porque o endereço do webhook costuma ser técnico, às vezes de um integrador terceiro, e quem deixa de receber pedido é o restaurante. Se os dois forem iguais, o e-mail sai uma vez só.
Nenhum pedido é perdido
Enquanto o webhook está desativado, os pedidos continuam sendo criados normalmente. Para recuperar o que não foi entregue, use:
GET /v1/orders/polling
A rota mantém uma janela das últimas 8 horas e devolve só o que mudou desde a sua última consulta, no mesmo formato do corpo do webhook. Quem já trata webhook reaproveita o mesmo código.
Se a desativação passou de 8 horas, use GET /v1/orders com filtro de período para reconciliar o intervalo que ficou fora da janela.
Como voltar a receber
Siga esta ordem: religar antes de corrigir só gasta as 5 tentativas de novo.
- Confirme que o endereço responde
2xx. Teste com umPOSTde fora da sua rede, não delocalhost. O endereço precisa ser HTTPS e acessível pela internet. - Responda antes de processar. Devolva
2xxao receber e processe depois, em fila. Resposta que demora mais de 15 s é timeout, e timeout é falha. - Reative o webhook no painel do Developers, em Webhooks.
O secret não muda com a desativação: não é preciso cadastrar webhook novo nem atualizar a validação do header X-Webhook-Secret.
Causas mais comuns
| Último erro | Causa provável |
|---|---|
HTTP 404 | Caminho errado na URL cadastrada, ou rota removida num deploy |
HTTP 401 ou HTTP 403 | O destino exige autenticação. Cadastre usuário e senha no webhook, e nós enviamos Basic Auth |
HTTP 500 | O seu handler lançou exceção. Responda 2xx primeiro e processe depois |
HTTP 301 ou HTTP 302 | Redirecionamento não é seguido. Cadastre a URL final |
| timeout | Processamento síncrono demorando mais de 15 s |
| Erro de conexão ou TLS | Certificado inválido ou expirado, ou servidor fora do ar |
Atenção ao 301: trocar de domínio e deixar o redirecionamento no ar não resolve, porque a entrega não segue o redirecionamento.
Perguntas frequentes
6 perguntas