PT EN

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#

bash
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:

json
{
  "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.

Próximos passos#