Webhooks que fallan: cómo encontrar la causa
Respuesta corta: Cuando un webhook falla, el reflejo es culpar al emisor. En la práctica, la mayoría de los casos se explica por tres conductas del receptor: responde demasiado lento y el emisor corta, no es idempotente y procesa dos veces el mismo evento, o asume un orden de llegada que nadie garantizó. Antes de escalar con el proveedor, comprueba qué respondió tu endpoint y en cuánto tiempo. Si no tienes ese registro, ese es el primer hallazgo. Un receptor correcto acepta rápido, guarda el evento, responde, y recién después procesa; y trata cada evento como algo que puede llegar repetido.
Primero: ¿qué respondió tu endpoint?
Antes de abrir un ticket con el proveedor, necesitas saber qué contestó tu propio sistema y en cuánto tiempo. El emisor decide reintentar en función de eso. Sin ese registro, cualquier conversación es especulación.
Si descubres que no guardas el código de respuesta ni la duración de cada llamada entrante, ya encontraste algo que arreglar antes de seguir buscando. Ese registro es barato y convierte un misterio en un dato.
Las tres causas más frecuentes están en el receptor
| Síntoma | Causa habitual | Qué revisar |
|---|---|---|
| El evento llega dos veces | El receptor responde tarde y el emisor reintenta | Tiempo de respuesta y clave de idempotencia |
| Faltan eventos | El receptor devolvió error y agotó los reintentos | Registro de respuestas por evento |
| Los datos quedan mal | Se asumió un orden de llegada | Marca de tiempo y versión del recurso |
El orden merece atención aparte. Que un evento se haya generado antes no garantiza que llegue antes. Si tu lógica depende de la secuencia, tiene que usar el dato de tiempo o de versión que trae el evento, no el momento en que lo recibiste.
Acepta rápido, procesa después
El patrón que evita la mayoría de estos problemas es simple: recibe, valida que el mensaje sea auténtico, guárdalo, responde de inmediato y procesa en otro momento. Así una base de datos lenta o un servicio externo caído dejan de traducirse en eventos perdidos.
Este cambio suele ser pequeño en código y grande en estabilidad. También hace que el reproceso sea posible: si el evento quedó guardado, puedes volver a ejecutarlo cuando corrijas el error.
Verifica que el evento es auténtico
Un endpoint que acepta cualquier cosa que llegue a esa URL es un problema de seguridad, no solo de confiabilidad. Revisa que se valide la firma o el mecanismo de autenticación que el emisor provee, y que esa validación no se haya desactivado «temporalmente» para depurar.
Prepara la conversación
Ordena los antecedentes con nuestro checklist de integración de sistemas. Si los eventos perdidos ya están afectando la operación, mira el alcance de la evaluación de integraciones y APIs y escríbenos con el sistema emisor, el volumen diario y desde cuándo ocurre.
Preguntas frecuentes
¿Por qué recibo el mismo evento dos veces?
Porque casi todos los emisores reintentan cuando no reciben confirmación a tiempo. Si tu endpoint procesó el evento pero respondió tarde, el emisor lo reenvía y tu sistema lo vuelve a procesar. La solución está en tu lado: identificar el evento y descartar el repetido.
¿Conviene procesar el webhook en el mismo request?
Normalmente no. Si el procesamiento es lento o depende de otros servicios, conviene aceptar, persistir y responder de inmediato, dejando el trabajo para un proceso aparte. Así una demora externa deja de provocar reintentos.