Responsabilidade
O recebimento de webhook tem três responsabilidades:- Registrar a entrega externa de forma rastreável.
- Garantir idempotência por provider e identificador externo do evento.
- Traduzir eventos reconhecidos para efeitos de negócio em um contexto específico.
Idempotência
Um webhook é identificado pelo parexternalProvider + externalEventId. Esse par representa o mesmo evento externo, mesmo que o provider entregue o payload mais de uma vez.
| Situação | Comportamento |
|---|---|
| Primeira entrega | O evento é registrado e encaminhado para o contexto responsável. |
| Entrega repetida | O registro existente é preservado, receivedCount aumenta e lastReceivedAt é atualizado. |
| Evento já processado | O efeito de negócio não é duplicado. |
| Falha no processamento | O erro fica registrado para acompanhamento e retry operacional. |
Modelo genérico
O modelo genérico de webhook é independente do provider e do contexto de negócio. Ele guarda os identificadores externos, o payload original, a ação derivada e o estado de processamento.| Campo | Papel |
|---|---|
webhookId | Identificador interno do registro. |
externalProvider | Provider que entregou o evento. |
externalEventId | Identificador único do evento no provider. |
externalEventType | Tipo original do evento no provider. |
actionType | Ação interna derivada do evento. |
payload | Conteúdo original recebido. |
status | Estado de processamento do webhook. |
receivedCount | Quantidade de entregas recebidas para o mesmo evento. |
lastReceivedAt | Data da última entrega recebida. |
processedAt | Data do processamento bem-sucedido, quando houver. |
Contextos
Billing
Eventos externos de billing mapeados para pagamento, pedido, recebíveis, transferência e conta bancária.