Eventos & Webhooks — Visão Geral

Esta seção concentra a documentação de eventos da plataforma FinWAY, entregues aos integradores via webhooks.

Domínios de evento observados

Domínios documentados no catálogo de payloads [FATO — docs/dados/eventos/webhooks]:

Domínio	Exemplos de evento (conforme catálogo)
PIX	PIX_CREATED, PIX_UPDATED
Charge	eventos de cobrança
Account Holder	eventos de titular
Transaction	eventos de transação
Individual Person	eventos de pessoa física
Company	eventos de pessoa jurídica
Account	eventos de conta
Product	eventos de produto

A lista completa de eventos e a estrutura de cada payload está na Referência de Webhooks.

Guia de integração × Referência de payloads

• Guia de jornada (Webhooks): explica o que são webhooks e quando usar — narrativa de integração.
• Referência de payloads (Referência de Webhooks): catálogo técnico dos eventos e seus JSONs.
• API Reference (Webhooks): endpoints de configuração de webhook, gerados de finway.json.

Status da documentação

• Atual: catálogo de payloads em Markdown manual (migrado de documentation/finaya-webhooks.md) [FATO].
• Futuro: descrição formal em AsyncAPI, com geração automática das páginas — ver Roadmap AsyncAPI.

Lacunas conhecidas

Os itens abaixo não estão documentados nas fontes atuais e não devem ser presumidos como implementados de determinada forma. São explicitados aqui como pendências: [TODO]

• Retry / reenvio — política de retentativa de entrega não documentada.
• Assinatura / autenticidade — verificação de origem do webhook (ex.: HMAC/assinatura) não documentada.
• Ordenação — garantia de ordem de entrega dos eventos não documentada.
• Idempotência de entrega — identificador de evento / deduplicação no consumidor não documentada.
• DLQ (Dead Letter Queue) — tratamento de falhas de entrega não documentado.
• SLA de entrega — latência/garantias de entrega não documentado.

Essas lacunas são candidatas naturais ao schema AsyncAPI (ver roadmap) e devem ser preenchidas pelos times donos dos eventos.