Reentrega e confiabilidade

Entregas de webhook podem falhar — seu servidor pode estar fora do ar, demorar demais para responder, ou devolver um erro. Esta página descreve como a FonteData lida com isso e o que sua aplicação precisa fazer para não processar o mesmo evento duas vezes.

Retentativas com backoff

Se a entrega não receber um status 2xx (timeout, redirecionamento, erro 4xx/5xx, indisponibilidade), o evento é reenviado automaticamente com backoff crescente, por até 24 horas a partir da primeira tentativa.

Isso significa que uma instabilidade passageira no seu endpoint — um deploy, um pico de carga — não perde o evento: ele volta a ser tentado depois.

Deduplicação por event_id

Como as tentativas de reentrega repetem a mesma requisição, seu endpoint pode receber o mesmo evento mais de uma vez — inclusive em cenários em que a entrega foi bem-sucedida, mas a confirmação (2xx) se perdeu no caminho de volta.

Por isso, trate a entrega como "pelo menos uma vez" (at-least-once), não "exatamente uma vez": use o event_id do envelope como chave de deduplicação — por exemplo, gravando os event_id já processados e ignorando qualquer entrega repetida.

# Exemplo simples de deduplicação
eventos_processados = set()  # em produção, use um armazenamento persistente

def processar_evento(evento: dict):
    event_id = evento["event_id"]
    if event_id in eventos_processados:
        return  # já processado, ignora
    eventos_processados.add(event_id)
    # ... lógica de negócio ...

Depois das 24 horas

Se o seu endpoint continuar indisponível (ou continuar respondendo erro) pelo período inteiro de retentativas, a entrega é marcada como definitivamente não entregue ao final das 24 horas — a FonteData não tenta mais esse evento específico.

Como o webhook é hoje o único caminho de entrega dessas respostas, um evento que esgota as 24 horas não é recuperável pela API. Vale tratar a saúde do seu endpoint como parte da operação: acompanhe o contador de falhas na tela de Webhooks do painel e prefira responder 2xx rápido, enfileirando o processamento (veja a seção seguinte), a segurar a resposta enquanto processa.

Responda rápido, processe depois

Seu endpoint tem até 10 segundos para responder 2xx a cada tentativa de entrega (veja Visão geral). Se o processamento do evento envolve trabalho mais demorado — gravar em banco, chamar outro serviço, disparar uma notificação — não faça isso de forma síncrona antes de responder.

O padrão recomendado é:

1. Receber a requisição e verificar a assinatura (veja Assinatura e verificação).
2. Checar o event_id contra os eventos já processados (deduplicação).
3. Enfileirar o evento para processamento assíncrono (fila, job em background).
4. Responder 200 OK imediatamente.

Isso reduz a chance de timeout — e, por consequência, de reentregas e duplicatas desnecessárias — mesmo quando o processamento real do evento leva mais tempo.