Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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/json

Recomendações

  • HTTPS obrigatório — configure seus endpoints exclusivamente com HTTPS (as webhookUrls precisam iniciar com https://).

  • Valide o header — sempre verifique o authKey/authValue antes de processar o payload.

  • Responda rápido — confirme com 2xx o 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:

  1. Validar o header de autenticação (authKey/authValue); rejeitar com 401 se inválido.

  2. Deduplicar por (data.requestId, eventType): se você já processou esse par, responda 2xx e ignore.

  3. Confirmar com 2xx imediatamente (ack), antes de qualquer processamento pesado.

  4. 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