Por que webhook delivery não basta para integrações financeiras confiáveis

Delivery acknowledgement é apenas uma fronteira

Um 2xx pode significar accepted, queued ou fully processed. Defina quando o evento se torna durable e o que ocorre se processing falhar depois do acknowledgement.

Consumers precisam de idempotent handling

Assuma duplicate delivery e use stable event IDs ou business keys persistentes. Um set em memória não sobrevive restarts.

Ordering deve ser explícito

Eventos distribuídos podem chegar tarde ou fora de ordem. Use versions, timestamps, state transitions ou reconciliation reads em vez de assumir network order = business order.

Recovery precisa de outra source of truth

Periodic reconciliation, provider fetch APIs, replayable stores ou backfill endpoints permitem reconstruir state quando eventos se perdem.

Defina delivery, acceptance e processing como eventos diferentes

O provider enviar webhook, o edge receber, a application aceitar e a domain transaction fazer commit são eventos distintos. O sistema deve saber qual boundary o 2xx reconhece. Se responde success antes de persistência durable, um crash pode perder o evento quando o provider já parou retries. Se espera workflow longo, retries podem criar duplicates desnecessários.

Um padrão comum é autenticar e validar, persistir ou enqueue durable, responder rápido e processar domain a partir desse registro. A implementação varia, mas o boundary deve ser intencional e observável.

Autentique eventos sem tornar delivery frágil

Webhook security normalmente inclui verificação de signature/secret, timestamp e transport security. Se o provider exige raw payload ou canonical form, use-o porque parse e reserialize de JSON pode invalidar signatures. Key rotation e clock skew também precisam de operação adequada.

Security failures devem ser métrica separada de application failures. Aumento de signature failures pode indicar misconfiguration, rotation issue ou malicious traffic; esconder em 4xx genérico oculta a causa.

Desenhe idempotency no domain boundary

Deduplicar por event ID evita repetir side effects da mesma entrega, mas pode não proteger de eventos semanticamente duplicados com IDs distintos. Quando a ação de negócio importa—marcar invoice paid ou criar refund—use também domain constraints e state transitions.

Idempotent processing deve incluir emails, ledger entries, inventory changes e downstream messages. Um handler que atualiza database uma vez mas envia duas notificações não é operacionalmente idempotente.

Trate ordering como problema de state machine

Redes não garantem ordem de eventos. Um estado posterior pode chegar primeiro ou um evento antigo ser retry depois de um novo. Consumers devem validar se a transição ainda é legal usando resource version, timestamps, sequence data ou fresh provider read quando necessário.

O objetivo não é ordenar tudo globalmente. É impedir que o domain regrida para estado impossível. Payment state machines devem tolerar evidência repetida e atrasada sem corromper o resultado final.

Construa replay e reconciliation desde o primeiro dia

Assuma que alguns eventos serão perdidos por deploy errors, credentials vencidas, configuration mistakes ou incidents do provider. Guarde history ou references suficientes para replay seguro. Reconcilie periodicamente recursos importantes contra o provider para descobrir gaps silenciosos.

Isso muda incident response: em vez de perguntar se cada webhook chegou, pergunte se o estado financeiro local pode ser provado correto e qual cohort precisa de replay ou reconciliation. É um reliability objective mais forte.