Delivery acknowledgement es solo una frontera
Un 2xx puede significar accepted, queued o fully processed. Define exactamente cuándo el evento es durable y qué pasa si processing falla después del acknowledgement.
Consumers necesitan idempotent handling
Asume duplicate delivery y usa stable event IDs o business keys persistentes. Un set en memoria no sobrevive restarts.
Ordering debe ser explícito
Eventos distribuidos pueden llegar tarde o desordenados. Usa versions, timestamps, state transitions o reconciliation reads en vez de asumir network order = business order.
Recovery necesita otra source of truth
Periodic reconciliation, provider fetch APIs, replayable stores o backfill endpoints permiten reconstruir state si un evento se pierde.
Define delivery, acceptance y processing como eventos diferentes
Que el provider envíe webhook, que edge lo reciba, que application lo acepte y que domain transaction haga commit son eventos separados. El sistema debe saber qué boundary reconoce el 2xx. Si responde success antes de persistencia durable, un crash puede perder el evento cuando provider ya dejó de reintentar. Si espera un workflow largo, los retries pueden generar duplicates innecesarios.
Un patrón común es autenticar y validar, persistir o enqueue durable, responder rápido y procesar domain desde ese registro. La implementación varía, pero el boundary debe ser intencional y observable.
Autentica eventos sin hacer frágil el delivery
Webhook security suele incluir verificación de signature/secret, timestamp y transport security. Si el provider exige raw payload o canonical form, úsalo porque parsear y reserializar JSON puede invalidar firmas. Key rotation y clock skew también necesitan manejo operativo.
Los security failures deben ser métrica aparte de application failures. Un aumento de signature failures puede indicar misconfiguration, problema de rotation o tráfico malicioso; esconderlo en 4xx genérico oculta la causa.
Diseña idempotency en el domain boundary
Deduplicar por event ID evita repetir side effects de la misma entrega, pero no siempre protege contra eventos semánticamente duplicados con diferentes identidades de transporte. Cuando importa la acción de negocio—marcar invoice paid o crear refund—usa también domain constraints y state transitions.
Idempotent processing debe incluir emails, ledger entries, inventory changes y downstream messages. Un handler que actualiza database una vez pero envía dos notificaciones no es operacionalmente idempotente.
Trata ordering como problema de state machine
Las redes no garantizan orden de eventos. Un estado posterior puede llegar primero o un evento antiguo reintentarse después de uno nuevo. Consumers deben validar si una transición sigue siendo legal usando resource version, timestamps, sequence data o fresh provider read cuando corresponda.
No se trata de ordenar todo globalmente. Se trata de impedir que el domain regrese a un estado imposible. Payment state machines deben tolerar evidencia repetida y tardía sin corromper el resultado final.
Construye replay y reconciliation desde el primer día
Asume que algunos eventos se perderán por deploy errors, credentials vencidas, configuration mistakes o incidents de provider. Conserva suficiente history o references para replay seguro. Reconcilia periódicamente recursos importantes contra el proveedor para descubrir gaps silenciosos.
Esto cambia incident response: en vez de preguntar si llegó cada webhook, pregunta si el estado financiero local se puede demostrar correcto y qué cohort necesita replay o reconciliation. Es un objetivo de reliability más fuerte.
Define la garantía real del acknowledgement.
Procesa idempotentemente.
No asumas orden de llegada.
Mantén un recovery path independiente.