Novas tentativas e reenvios
O calendário de novas tentativas, quando uma entrega fica guardada em vez de repetida, como muda a saúde do endereço e como reenviar à mão ou em lote.
Uma entrega fica concluída quando o seu endereço responde com qualquer estado 2xx em menos de 10 segundos. Tudo o resto, incluindo tempo esgotado, ligação recusada ou redireccionamento, conta como tentativa falhada. O passo seguinte depende da resposta recebida.
Calendário por omissão#
Depois de uma tentativa falhada, a entrega volta a pending com um next_attempt_at. As esperas após cada falha são de 30 segundos, 2 minutos, 10 minutos, 30 minutos, 1 hora, 2 horas, 4 horas e 8 horas; a partir daí, de 12 em 12 horas. A cada espera junta-se até 10% de variação aleatória, para que as tentativas de muitas entregas não cheguem todas ao mesmo tempo. A entrega termina como failed ao fim de 15 tentativas ou quando faz 72 horas, o que acontecer primeiro. O limite de 72 horas é uma definição do servidor que o operador da instalação pode alterar; o calendário e as 15 tentativas são fixos.
Respostas que levam a nova tentativa#
| Resposta do seu servidor | Resultado |
|---|---|
2xx |
succeeded. |
5xx, 408, 425, 429, tempo esgotado ou erro de ligação |
Nova tentativa segundo o calendário acima. |
Outro 4xx qualquer |
Enviada duas vezes no total e depois guardada como paused até agir. |
410 Gone |
O endereço é pausado automaticamente e as entregas na fila ficam guardadas. |
Uma entrega guardada não se perde enquanto espera, mas passa a failed quando atinge a idade máxima.
Saúde do endereço#
Cada endereço tem um campo health. Passa a degraded depois de três tentativas falhadas seguidas, a failing quando as falhas se prolongam por 24 horas e a paused_automatically ao fim de 72 horas de falhas. Se for o utilizador a pausar, fica paused_by_owner. Cada mudança provocada por uma tentativa de entrega fica no registo de auditoria como developer.webhook.health_changed; a pausa ou retoma feita à mão fica registada como developer.webhook.updated ou developer.webhook.resumed. Uma única tentativa bem-sucedida repõe a contagem a zero.
As entregas sobre o mesmo registo mantêm a ordem: enquanto um evento anterior sobre uma factura não for entregue, o seguinte sobre essa factura espera atrás dele.
Reenviar uma entrega#
curl -sS -X POST "$BUSINESS_API/developer/deliveries/dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU/retry" \
-H "Authorization: Bearer $API_KEY"
A resposta 202 mostra a entrega de novo pendente, com um orçamento de tentativas renovado:
{
"id": "dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"webhook_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
"url": "https://erp.example.test/hooks/billing",
"event_id": "wev_2kP9bR7nWu2JfT5xQ1mKhB8cVzD",
"event_type": "invoice.paid",
"status": "pending",
"attempts": 15,
"max_attempts": 30,
"next_attempt_at": "2026-11-19T10:31:05.204118Z",
"response_status": 503,
"duration_ms": 412,
"created_at": "2026-11-16T10:12:44.930551Z",
"sequence": 4
}
A operação responde 409 enquanto a entrega está a ser tentada ou quando o webhook já foi apagado. No painel, a mesma acção é o botão Reenviar na página da entrega.
Reenviar em lote#
POST $BUSINESS_API/developer/webhooks/{id}/redeliveries devolve à fila as entregas failed e paused de um endereço num período de 7 dias no máximo (from e to, em RFC 3339). Pode restringir com types e statuses (que aceita também cancelled). Envie primeiro "dry_run": true: a resposta 200 indica a contagem em requeued sem alterar nada. A chamada real responde 201 com um identificador wrd_. No painel, esta acção é Reenviar falhadas, na página do webhook.
Novas tentativas, reenvios e reenvios em lote usam a mesma entrega, por isso o webhook-id nunca muda.