Un webhook es un mensaje HTTP asíncrono, no una llamada de función garantizada. El emisor puede reintentar, los eventos llegan tarde o desordenados, el endpoint puede caer y un handler lento provoca otra entrega. Una integración sólida asume duplicados y hace cada paso visible y recuperable.
No ejecutes todo el flujo de negocio antes del acuse. GitHub, por ejemplo, espera 2xx en hasta 10 segundos y recomienda una cola asíncrona para trabajo largo. El plazo depende del proveedor: revisa el contrato de entrega y reintentos de cada integración.
Usa HTTPS y verifica la firma sobre el cuerpo bruto exacto antes de analizarlo o cambiar estado. Guarda el secreto en un gestor, compara MAC en tiempo constante y planifica rotación controlada. Si la firma incluye timestamp, valida su ventana. La allowlist de IP es defensa adicional, no sustituto de firma; las direcciones pueden cambiar.
Limita tamaño, tipo de contenido, secreto por endpoint y eventos aceptados. No pongas secretos en URLs. Una firma válida acredita emisor e integridad, no que todos los campos sean seguros ni que el evento corresponda al cliente adecuado.
| Identificador | Uso | No supongas |
|---|---|---|
| ID de entrega del proveedor | Deduplicar reintentos de transporte y rastrear soporte. | Que siempre identifique la acción de negocio entre proveedores. |
| Objeto/versión de negocio | Validar transición y versión de origen. | Que eventos lleguen en orden de creación. |
| ID interno de proceso | Relacionar intento, efectos y logs. | Que un reintento sea un evento nuevo. |
Guarda el ID de entrega con restricción de unicidad. Algunos emisores conservan el mismo ID al reentregar manualmente; registra intentos aparte si soporte lo necesita. Eventos distintos pueden representar una misma acción, por lo que la idempotencia también pertenece a la operación de negocio.
Persiste la entrega antes de responder éxito. Una outbox transaccional o dispatcher recuperable evita perder trabajo si el proceso cae entre el commit y la publicación en cola. El consumidor registra el estado y hace idempotentes los efectos externos: pasa clave a pagos/correo/CRM cuando se admita o usa un ledger local. La transacción SQL no vuelve atómica una llamada HTTP independiente.
Reintenta errores transitorios de red, rate limit y dependencias con backoff exponencial y jitter; respeta Retry-After cuando aplique. No repitas indefinidamente errores permanentes de esquema o permisos. Tras un límite, mueve el mensaje a dead letter/cuarentena con motivo, intentos y fechas. Alerta por edad de cola y fallos repetidos; una DLQ desatendida solo esconde el fallo.
Usa versiones de origen, fecha de actualización o reglas de dominio si el orden importa. Consulta el estado actual de origen en transiciones críticas si el contrato lo permite. No apliques una cancelación antigua sobre una reactivación reciente porque llegó después. Conserva hora del evento, recepción y procesamiento para diagnosticar retrasos.
El operador necesita buscar por ID, cliente, tipo, objeto y fecha; revisar verificación y procesamiento; reintentar sin duplicar efectos y comparar estado con el origen. Replay conserva la identidad original y registra un nuevo intento. Oculta datos personales en logs y define retención de payloads. La conciliación detecta eventos que nunca llegaron o agotaron sus reintentos.
Prueba firma inválida, cuerpo alterado, duplicados, dependencias lentas, caída de base/cola, crash después del commit, rate limit, redelivery, orden invertido y payload problemático. Comprueba que el acuse ocurre tras aceptación duradera y que repetir no repite efectos. Usa sandbox y herramientas del proveedor antes de producción.
Los webhooks confiables combinan entrada autenticada breve, aceptación duradera, acuse rápido, procesamiento asíncrono idempotente, reintentos limitados, dead letters visibles y replay seguro. Esta arquitectura discreta evita que pagos, provisión y estado del cliente dependan de una única petición HTTP en el instante perfecto.