Seu endpoint recebe um POST por evento e precisa responder com status 2xx em até 8 segundos. Qualquer outra resposta conta como falha, e o evento é tentado de novo até 3 vezes, com cerca de 3 minutos entre as tentativas.
Requisitos do endpoint
HTTPS e POST, com corpo JSON. O formato está no artigo Referência de eventos e campos.
Responda 2xx em até 8 segundos. O prazo conta tudo: resolução do endereço, conexão, TLS, envio e resposta. Se o seu processamento for demorado, guarde o evento numa fila sua, responda 2xx e processe depois.
Autenticação por header. Enviamos em toda chamada os headers que você cadastrou na tela, como
Authorization: Bearer seu-token. Valide esse valor no seu servidor e recuse chamadas sem ele. O corpo não é assinado.Não use resposta compactada. Pedimos o corpo sem compressão (
Accept-Encoding: identity) e não lemos o conteúdo da resposta, só o status. Quando a entrega falha, guardamos o começo da resposta para mostrar no histórico.
Ordem dos eventos
Os eventos de uma mesma conversa chegam ao seu endpoint na ordem em que aconteceram. A ordem vale por conversa e por webhook: conversas diferentes são entregues em paralelo, e um webhook lento não atrasa os outros webhooks da sua loja.
Para manter a ordem, quando uma entrega falha, os próximos eventos daquela conversa esperam as novas tentativas terminarem. Os eventos de outras conversas continuam saindo normalmente.
Os eventos de campanha de um mesmo envio, ou seja, a mensagem de uma campanha para um contato, chegam em ordem. Envios diferentes, inclusive de outras campanhas para o mesmo contato, são entregues em paralelo, sem ordem entre si.
Tentativas
Tentativa | Quando |
1ª | Assim que o evento acontece. |
2ª | Cerca de 3 minutos depois da primeira falha. |
3ª | Cerca de 3 minutos depois da segunda falha. |
Depois de 3 tentativas sem resposta 2xx, o evento não é reenviado e aparece em Erros recentes, no histórico do webhook. Se o seu endpoint ficar fora do ar, os eventos desse período se perdem: não há reenvio manual pela tela.
Enquanto um evento está em nova tentativa, os próximos da mesma conversa esperam e também gastam tentativas. Se o primeiro esgotar as 3 tentativas, alguns dos seguintes podem ser descartados sem nunca terem sido enviados.
Eventos repetidos
A entrega é "pelo menos uma vez": o mesmo evento pode chegar mais de uma vez. Isso acontece, por exemplo, quando seu endpoint processa o evento, mas a resposta não chega a tempo.
Use o campo traceId para ignorar repetições: ele identifica o evento, e toda nova tentativa repete o mesmo valor. Guarde os traceId que você já processou e descarte os repetidos.
Pausa automática de um endpoint fora do ar
Quando um webhook falha 10 vezes seguidas, pausamos as entregas para ele por 5 minutos. Ao fim da pausa, fazemos uma entrega de teste:
se der certo, as entregas voltam ao normal;
se falhar, começa uma nova pausa de 5 minutos.
A pausa vale só para aquele webhook. Os outros webhooks da sua loja continuam recebendo. Durante a pausa, os eventos não são enviados e contam como tentativa. No histórico, aparecem como Envio pausado após falhas seguidas.
E se o meu endpoint ficar fora do ar por horas?
Os eventos desse período não chegam ao seu sistema e não são reenviados automaticamente. Cada evento tem 3 tentativas em cerca de 6 minutos. Depois disso, ele aparece em Erros recentes e não é tentado de novo.
O que acontece durante a queda:
As entregas falham, e cada evento passa pelas 3 tentativas.
Depois de 10 falhas seguidas, pausamos as entregas para esse webhook por 5 minutos e testamos o endpoint ao fim de cada pausa.
Os eventos que acontecem durante a pausa não são enviados e também se esgotam depois das 3 tentativas.
Quando o endpoint volta:
as entregas recomeçam em até cerca de 5 minutos, no próximo teste;
os eventos dos últimos minutos antes disso também podem se perder;
os eventos novos chegam normalmente, na ordem de cada conversa.
A queda afeta só esse webhook. Os outros webhooks da sua loja continuam recebendo normalmente.
Você não recebe um aviso automático quando o endpoint para de responder. Acompanhe a taxa de erro na lista de webhooks e os Erros recentes no histórico. O artigo Histórico de entregas e erros comuns explica cada erro.
Como se proteger:
Responda 2xx logo ao receber o evento e processe depois, numa fila do seu lado. Assim, uma lentidão no seu sistema não vira falha de entrega.
Monitore seu endpoint e confira o histórico de entregas sempre que mudar algo nele.
Webhook inativo
Um webhook com Ativo desligado não recebe eventos. O que acontece enquanto ele está inativo não é enviado depois que você reativar.