Política de retentativas, backoff exponencial e boas práticas para garantir a entrega confiável de webhooks.
Se o seu servidor não responder com um status HTTP 2xx, a Worldfy reenvia a notificação automaticamente com backoff exponencial.
| Tentativa | Atraso | Tempo acumulado |
|---|---|---|
| 1a | 30 segundos | 30s |
| 2a | 1 minuto | 1min 30s |
| 3a | 5 minutos | 6min 30s |
| 4a | 15 minutos | 21min 30s |
| 5a | 30 minutos | 51min 30s |
| 6a | 1 hora | 1h 51min |
| 7a | 2 horas | 3h 51min |
| 8a | 4 horas | 7h 51min |
| 9a | 8 horas | 15h 51min |
| 10a | 24 horas | ~40h |
Após 10 tentativas sem sucesso, a entrega é marcada como exhausted (esgotada) e não será mais reenviada. O ciclo completo de retentativas cobre aproximadamente 40 horas.
| Status | Descrição |
|---|---|
pending | Entrega pendente (aguardando envio) |
success | Entregue com sucesso (resposta 2xx) |
failed | Falha na entrega (será retentada) |
exhausted | Todas as tentativas esgotadas |
Você pode auditar as entregas dos seus webhooks pelos logs de entrega:
curl -X GET "https://api.worldfypayments.com/v1/postbacks/delivery-logs?status=failed&page=1&limit=20" \
-H "Authorization: Basic {credentials}"| Parâmetro | Tipo | Descrição |
|---|---|---|
status | string | pending, success, failed ou exhausted |
event_name | string | Filtra por nome do evento (ex: charge.captured) |
page | number | Página (padrão 1) |
limit | number | Itens por página (padrão 20) |
Cada log inclui status, attempt, max_attempts, response_status_code, error_message, next_retry_at e delivered_at, entre outros campos.
Uma entrega pode ser reenviada manualmente a qualquer momento:
curl -X POST https://api.worldfypayments.com/v1/postbacks/delivery-logs/{id}/resend \
-H "Authorization: Basic {credentials}"Sua aplicação deve:
2xx (200, 201, 202, etc.)Não processe a lógica de negócios antes de responder ao webhook. Responda 200 OK imediatamente e processe o evento de forma assíncrona.
O mesmo evento pode ser entregue mais de uma vez (em caso de timeout ou falha de rede). Use o campo id do payload como chave de idempotência para evitar processamento duplicado.
Mantenha o tempo de resposta abaixo de 5 segundos. Se o processamento do evento é demorado:
200 OK imediatamenteSempre valide a assinatura HMAC antes de processar qualquer evento. Isso garante que a notificação veio da Worldfy e não foi adulterada.
Monitore falhas de entrega. Se muitas notificações estão falhando, verifique: