# 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

- [Fazer o receptor ignorar entregas repetidas](/docs/webhooks/best-practices)
- [Consultar o histórico de entregas durante os testes](/docs/webhooks/testing)
- [Como são devolvidos erros como o 409](/docs/getting-started/errors)

