Retries
Uma entrega que não termina em 2xx é retentada. São no máximo 6 tentativas por destino, com
esperas crescentes entre elas.
A agenda
| Tentativa | Sai quando |
|---|---|
| 1 | assim que o evento acontece |
| 2 | 1 min depois da falha da 1ª |
| 3 | 5 min depois da falha da 2ª |
| 4 | 30 min depois da falha da 3ª |
| 5 | 2 h depois da falha da 4ª |
| 6 | 12 h depois da falha da 5ª |
Se a 6ª também falhar, a entrega fica com status: dead e não é mais retentada sozinha. Do evento
até o dead passam cerca de 14 h e 36 min. Quem quiser recuperar um evento morto usa o
reenvio manual.
Cada tentativa é uma linha própria em webhook-deliveries, com o seu X-Delivery-Id e o
X-Attempt correspondente. O X-Event-Id é o mesmo nas 6.
As tentativas de um destino não seguram as de outro: se a sua conta tem endpoint e a cobrança tem
postback_url, as duas entregas retentam em paralelo, cada uma com a sua agenda.
O que conta como falha
Retentado:
| Situação | error da entrega |
|---|---|
Resposta 4xx ou 5xx |
http_<status> |
Resposta 3xx |
redirect_not_followed |
| Sem resposta em 10 s | timeout |
| Conexão recusada, DNS quebrado, TLS inválido | connection_error |
Redirecionamento é falha de propósito: seguir um 3xx anularia a checagem de destino que roda
antes de cada entrega. Se você mudou de URL, atualize o endpoint em vez de redirecionar.
Não retentado, porque repetir não mudaria nada:
| Situação | error da entrega |
|---|---|
| Endpoint desativado ou removido entre o evento e a entrega | endpoint_disabled |
| A URL deixou de passar na checagem de destino (o DNS passou a apontar para rede privada, por exemplo) | blocked_destination |
| A store não tem segredo de postback configurado | missing_secret |
Desses três, só o primeiro é comum, e ele se resolve religando o endpoint: os eventos posteriores voltam a ser entregues normalmente, e os que falharam nesse meio-tempo você recupera pelo reenvio manual.
Sucesso é qualquer 2xx. O corpo da sua resposta é lido só até 1 KB, guardado como
response_body_excerpt para você depurar, e nunca interpretado: não adianta responder 2xx com um
JSON pedindo alguma coisa.
Desativação automática
Um endpoint que acumula 50 entregas dead seguidas sem nenhuma entrega bem-sucedida nos
últimos 7 dias é desativado. Na prática isso é um endpoint que saiu do ar e não voltou: em vez de
seguir enfileirando entregas que ninguém recebe, nós paramos.
Quando acontece, o endpoint fica com enabled: false, disabled_reason: "auto" e
auto_disabled_at preenchido, e um aviso aparece no feed do painel. disabled_reason é o que
distingue essa desativação de um desligamento que você mesmo fez pelo painel, que grava "manual".
Para reativar, conserte o seu endpoint e mande
PATCH /v1/me/webhook-endpoints/{id} com { "enabled": true }
(na referência). Religar
zera disabled_reason e auto_disabled_at. Os eventos que aconteceram enquanto ele estava
desligado não são reenviados sozinhos: use o reenvio manual ou reconcilie
pela consulta dos recursos.
Antes de religar, dispare um ping e confira que ele volta 2xx.
Acompanhar a saúde do endpoint
GET /v1/me/webhook-endpoints/{id}/stats
(na referência)
devolve a taxa de sucesso e o total de entregas dos últimos 7 dias, mais quando foi o último ping e
se ele deu certo. A taxa vem null, não 0, quando não houve entrega nenhuma na janela: zero
entrega não é zero por cento de sucesso.
Vale monitorar isso do seu lado. Uma taxa de sucesso caindo costuma aparecer bem antes do primeiro
dead, e muito antes dos 50 que desativam o endpoint.