Entregas e Retentativas

Como funciona o mecanismo de entrega de webhooks, retentativas e backoff exponencial

Status de entrega

Cada entrega de webhook possui um dos seguintes status:

Status	Descricao
`SUCESSO`	Entrega confirmada — seu endpoint retornou HTTP 2xx
`FALHA`	Entrega falhou apos esgotar todas as tentativas
`AGUARDANDO_RETENTATIVA`	Aguardando proxima tentativa automatica

Fluxo de entrega

Evento PIX ocorre
      |
      v
Despacho para todos os webhooks ativos do tipo
      |
      v
POST para URL do webhook (com headers de assinatura)
      |
      +--- HTTP 2xx ---> Status: SUCESSO
      |
      +--- Falha ------> Tentativa < 3?
                              |
                    Sim ----> Status: AGUARDANDO_RETENTATIVA
                    |         (agenda proxima tentativa)
                    |
                    Nao ----> Status: FALHA

Retentativas automaticas

Quando uma entrega falha (timeout, erro de rede, ou resposta HTTP diferente de 2xx), o servico agenda uma retentativa automatica com backoff exponencial.

Configuracao

Parametro	Valor
Total de tentativas	3 (incluindo a inicial)
Base do backoff	2 minutos
Timeout de conexao	3 segundos
Timeout de leitura	10 segundos
Tamanho maximo da resposta	4096 bytes

Intervalos de backoff

Tentativa	Intervalo	Formula
1a	Imediata	Entrega inicial
2a	2 minutos	`2 * 2^0`
3a	4 minutos	`2 * 2^1`

Apos a 3a tentativa falhar, o status final e FALHA e nenhuma retentativa adicional e agendada.

Retentativa manual

Voce pode retentar manualmente uma entrega com status FALHA:

POST /api/v1/webhooks/{id}/entregas/{entregaId}/retry

Isso cria uma nova entrega com seu proprio ciclo de retentativas. A entrega original nao e alterada.

Response `202 Accepted`

{
  "id": "novo-uuid-da-entrega",
  "webhookId": "550e8400-e29b-41d4-a716-446655440000",
  "eventoId": "770e8400-e29b-41d4-a716-446655440002",
  "status": "AGUARDANDO_RETENTATIVA",
  "tentativas": 0,
  "httpStatus": null,
  "responseBody": null,
  "payloadEnviado": [...],
  "tentadoEm": "2026-05-01T14:00:00",
  "proximaTentativaEm": "2026-05-01T14:00:00"
}

Consultando entregas

Liste as entregas de um webhook para monitorar o status:

GET /api/v1/webhooks/{id}/entregas?status=FALHA

Campos da resposta

Campo	Tipo	Descricao
`id`	UUID	Identificador da entrega
`webhookId`	UUID	Webhook associado
`eventoId`	UUID	Evento que originou a entrega
`status`	enum	`SUCESSO`, `FALHA` ou `AGUARDANDO_RETENTATIVA`
`tentativas`	int	Numero de tentativas realizadas
`httpStatus`	int	Status HTTP retornado pelo seu endpoint
`responseBody`	string	Body da resposta (truncado em 4096 bytes)
`payloadEnviado`	JSON	Payload completo enviado ao webhook
`tentadoEm`	datetime	Timestamp da primeira tentativa
`proximaTentativaEm`	datetime	Proxima tentativa agendada (null se finalizado)

Boas praticas para seu endpoint

Responda rapido — Retorne 2xx em ate 10 segundos (timeout de leitura). Processe o evento de forma assincrona se necessario
Seja idempotente — O mesmo evento pode ser entregue mais de uma vez. Use o header X-Event-Id para deduplicar
Retorne 2xx para sucesso — Qualquer status fora da faixa 200-299 e considerado falha e dispara retentativa
Valide a assinatura — Veja Seguranca e Assinatura para implementacao
Monitore entregas com falha — Consulte periodicamente as entregas com status FALHA e use a retentativa manual quando necessario

Entregas e Retentativas

On this page