Retries e idempotência de eventos

O que conta como sucesso

• Somente respostas 2xx são consideradas sucesso.
• Timeout de 10 segundos por tentativa.
• Redirecionamentos não são seguidos.
• Falha de conexão, timeout ou status não-2xx agendam nova tentativa.

Agenda de retentativas

São no máximo 7 tentativas: a inicial mais 6 retentativas.

Após a sétima tentativa sem sucesso, a entrega é marcada como falha definitiva. Consulte o histórico em GET /api/public/v1/webhooks/{id}/deliveries.

Idempotência de eventos

O id do evento (também enviado no header Pitra-Event-Id) permanece estável em todas as tentativas da mesma entrega — apenas Pitra-Attempt muda. Como a entrega é at-least-once, o mesmo evento pode chegar mais de uma vez.

const eventId = req.header("Pitra-Event-Id");

if (await alreadyProcessed(eventId)) {
  return res.status(200).send("ok"); // duplicata: ignore
}

await markProcessed(eventId);
await handle(JSON.parse(rawBody));