El acuse de recibo 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.
Los consumidores necesitan procesamiento idempotente
Supón que habrá entregas duplicadas y usa identificadores de evento estables o claves de negocio persistentes. Un conjunto en memoria no sobrevive a los reinicios.
El orden de los eventos debe ser explícito
Los eventos distribuidos pueden llegar tarde o desordenados. Usa versiones, marcas de tiempo, transiciones de estado o consultas de conciliación en lugar de suponer que el orden de la red equivale al orden comercial.
La recuperación necesita otra fuente de referencia
La conciliación periódica, las API de consulta del proveedor, los almacenes que permiten reproducir eventos o los puntos de acceso para completar datos permiten reconstruir el estado si se pierde un evento.
Define entrega, aceptación y procesamiento como eventos diferentes
Que el proveedor envíe un webhook, que el extremo de red lo reciba, que la aplicación lo acepte y que la transacción del dominio se confirme son eventos separados. El sistema debe saber qué límite reconoce el 2xx. Si responde con éxito antes de la persistencia duradera, un fallo puede hacer que se pierda el evento cuando el proveedor ya haya dejado de reintentar. Si espera a que termine un flujo de trabajo largo, los reintentos pueden generar duplicados 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 los eventos sin volver frágil la entrega
La seguridad de los webhook suele incluir la verificación de la firma o el secreto, la marca de tiempo y la seguridad del transporte. Si el proveedor exige el contenido original o un formato canónico, úsalo, porque analizar y volver a serializar JSON puede invalidar las firmas. La rotación de claves y la desviación del reloj también requieren gestión operativa.
Los fallos de seguridad deben ser una métrica aparte de los fallos de la aplicación. Un aumento de los fallos de verificación de firmas puede indicar una configuración incorrecta, un problema de rotación o tráfico malicioso; ocultarlo dentro de una categoría genérica de 4xx oculta la causa.
Diseña la idempotencia en el límite del dominio
Deduplicar por ID de evento evita repetir los efectos secundarios de una misma entrega, pero no siempre protege contra eventos duplicados desde el punto de vista semántico con identidades de transporte distintas. Cuando importa la acción de negocio —marcar una factura como pagada o crear un reembolso—, utiliza también restricciones del dominio y transiciones de estado.
El procesamiento idempotente debe incluir correos electrónicos, asientos contables, cambios de inventario y mensajes posteriores. Un controlador que actualiza la base de datos una vez, pero envía dos notificaciones, no es idempotente desde el punto de vista operativo.
Gestiona el orden de eventos mediante una máquina de estados
Las redes no garantizan el orden de los eventos. Un estado posterior puede llegar primero o puede volver a intentarse un evento antiguo después de uno nuevo. Los consumidores deben validar si una transición sigue siendo legal usando la versión del recurso, las marcas de tiempo, los datos de secuencia o una consulta actualizada al proveedor, según corresponda.
No se trata de ordenar todo de forma global, sino de impedir que el dominio vuelva a un estado imposible. Las máquinas de estados de pago deben tolerar evidencia repetida y tardía sin corromper el resultado final.
Incorpora reprocesamiento y conciliación desde el primer día
Supón que algunos eventos se perderán por errores de despliegue, credenciales vencidas, errores de configuración o incidentes del proveedor. Conserva suficiente historial o referencias para poder reproducirlos de forma segura. Concilia periódicamente los recursos importantes con el proveedor para descubrir brechas silenciosas.
Esto cambia la respuesta a incidentes: en lugar de preguntar si llegó cada webhook, pregunta si se puede demostrar que el estado financiero local es correcto y qué cohorte necesita reproducción o conciliación. Es un objetivo de confiabilidad más sólido.
Define la garantía real del acknowledgement.
Procesa idempotentemente.
No asumas orden de llegada.
Mantén una vía de recuperación independiente.