Segurança e Exemplos
Autenticação
Cada requisição de webhook inclui um header estático de autenticação, definido por você na subscription: o nome é o authKey e o valor é o authValue (ver Configuração via API). O serviço envia esse header — e só ele — em todas as entregas.
POST https://originator.example.com/callbacks/fgts
X-Webhook-Token: s3cr3t-t0k3n-v4lue
Content-Type: application/jsonRecomendações
HTTPS obrigatório — configure seus endpoints exclusivamente com HTTPS (as
webhookUrlsprecisam iniciar comhttps://).Valide o header — sempre verifique o
authKey/authValueantes de processar o payload.Responda rápido — confirme com
2xxo quanto antes e processe o payload de forma assíncrona se necessário.Idempotência — deduplique pelo par (
data.requestId,eventType), pois a entrega é at-least-once (ver Retry e Garantias de Entrega).
Idempotência por requestId e eventType
A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez em caso de falha de rede, timeout ou resposta não-2xx. Use o par (data.requestId, eventType) como chave de idempotência. O requestId sozinho não basta: a mesma operação emite mais de um evento — CANCEL_RESERVE_UNDER_REVIEW e depois CANCEL_RESERVE_FAILED, por exemplo — e deduplicar só por ele descarta o desfecho final.
Padrão recomendado para o receptor:
Validar o header de autenticação (
authKey/authValue); rejeitar com401se inválido.Deduplicar por (
data.requestId,eventType): se você já processou esse par, responda2xxe ignore.Confirmar com
2xximediatamente (ack), antes de qualquer processamento pesado.Processar o evento de forma assíncrona, roteando por
eventType.
Ver também Idempotência.
Exemplos de implementação
O corpo é um envelope com source, eventType e data. Use data como payload do evento e eventType para rotear.
Recebendo webhooks (Node.js / Express)
Recebendo webhooks (Python / Flask)
Recebendo webhooks (Java / Spring Boot)
Eventos *_NEEDS_VERIFICATION / status = EXPIRED
Os eventos ENDORSEMENT_NEEDS_VERIFICATION, MAINTAIN_GUARANTEE_NEEDS_VERIFICATION e CANCEL_RESERVE_NEEDS_VERIFICATION (com data.status = EXPIRED) indicam que a operação expirou aguardando a resposta da Caixa — o desfecho real ainda é incerto. Nesses casos, não assuma sucesso nem falha: o evento não traz result, e o error traz apenas code = EXPIRED_TTL, que marca a expiração e não é veredito da Caixa.
Confirmado por polling que a operação de fato não teve desfecho, uma averbação nesse estado é retentável — não é preciso abrir chamado nem submeter reserva nova.
Checklist de integração
Atualizado