¿Qué debería devolver un endpoint de webhook de seguimiento? ¿Códigos de estado, tiempos de espera y reintentos?
Un endpoint de webhook de seguimiento debe devolver una respuesta 2xx rápida e intencionada después de haber aceptado el evento para su procesamiento. En la mayoría de las integraciones, el patrón más seguro es autenticar la solicitud, validar la carga útil, almacenar o poner en cola el evento y confirmarlo con 200 OK o 202 Accepted. Utiliza respuestas 4xx para solicitudes que el remitente no debería volver a intentar y respuestas 5xx cuando un problema temporal del lado del servidor impidió la aceptación. El comportamiento exacto del tiempo de espera y los reintentos aún depende del contrato del proveedor del webhook, por lo que tu implementación debe diseñarse basándose en el comportamiento documentado del remitente y no en suposiciones.
Para un webhook de seguimiento o de estado del envío, esta distinción es importante porque los eventos de entrega pueden llegar más de una vez, llegar desordenados o reproducirse después de un fallo de red. La función del endpoint no consiste necesariamente en completar todas las operaciones empresariales antes de responder. Su primera función es tomar una decisión fiable sobre si el evento ha sido aceptado.
El contrato de respuesta en términos prácticos
Una respuesta de webhook tiene dos destinatarios: el sistema remitente y tu propia aplicación. El remitente necesita un resultado HTTP claro para decidir si debe marcar la entrega como exitosa, volver a intentarla o detenerse. Tu aplicación necesita tiempo suficiente para verificar y registrar el evento de forma duradera. Estos objetivos son más fáciles de cumplir cuando el endpoint tiene una pequeña ruta síncrona y una ruta de procesamiento asíncrona independiente.
- Recibe la solicitud HTTP a través de HTTPS.
- Comprueba la firma, las credenciales de autenticación, la marca de tiempo u otros controles de integridad de la solicitud requeridos por el proveedor.
- Analiza y valida la carga útil sin realizar operaciones posteriores lentas.
- Escribe el evento, o un registro de deduplicación y una referencia del evento, en un almacenamiento duradero o en una cola fiable.
- Devuelve una respuesta 2xx intencionada.
- Procesa de forma asíncrona la actualización del seguimiento, la notificación al cliente, el cambio de inventario u otra acción empresarial.
Una respuesta no debe afirmar que se ha aceptado el evento si este solo existe en la memoria del proceso. Si la aplicación falla inmediatamente después de devolver el resultado correcto, un evento que nunca se guardó puede perderse mientras el remitente cree que la entrega tuvo éxito. Por tanto, el momento en que devuelves 2xx debe coincidir con tu garantía real de durabilidad.
¿Qué código de estado debe devolver un webhook?
| Respuesta | Significado para el remitente | Uso habitual del webhook |
|---|---|---|
200 OK | La solicitud se aceptó y se gestionó correctamente. | Valor predeterminado práctico después de la validación y la aceptación duradera. |
202 Accepted | La solicitud se aceptó para su procesamiento, pero el trabajo puede continuar. | Útil cuando el evento se ha puesto en cola de forma segura, pero el procesamiento empresarial es asíncrono. |
204 No Content | La solicitud tuvo éxito y no se necesita un cuerpo de respuesta. | Adecuado cuando el proveedor acepta una respuesta exitosa vacía. |
400–499 | La solicitud es no válida, no está autorizada o no es aceptable tal como se envió. | Carga útil mal formada, autenticación fallida, firma no válida o evento rechazado permanentemente. |
429 Too Many Requests | El receptor está aplicando límites de frecuencia. | Utilízalo solo cuando el comportamiento de reintento del remitente y tu política de límites de frecuencia sean compatibles. |
500–599 | El receptor no pudo aceptar la solicitud debido a un problema del servidor o temporal. | Interrupción de la base de datos, fallo de la cola, fallo de una dependencia o error inesperado de la aplicación. |
200 OK suele ser la opción menos sorprendente porque se entiende ampliamente como una recepción exitosa. 202 Accepted también es útil semánticamente cuando el endpoint ha aceptado el evento para procesarlo más adelante. Ningún código es automáticamente correcto: la documentación del remitente puede definir qué respuestas 2xx cuentan como exitosas y algunos proveedores pueden esperar un cuerpo o tipo de contenido específico.
No devuelvas una respuesta 2xx simplemente porque la solicitud HTTP llegó a tu servidor. Si la verificación de la firma falla o la carga útil no puede interpretarse de forma segura, una respuesta 4xx suele ser más veraz. Del mismo modo, no devuelvas un 4xx por una interrupción temporal de la base de datos si el evento podría completarse más adelante. Una respuesta 5xx da al remitente con capacidad de reintento la oportunidad de entregar el evento de nuevo, aunque el proveedor puede aplicar su propia política.
¿Cómo deben gestionarse los tiempos de espera?
Los valores de tiempo de espera de los webhooks son específicos de cada proveedor. No existe un tiempo de espera HTTP universal que utilicen todas las plataformas de seguimiento, y un remitente puede dejar de esperar antes de que tu aplicación termine una operación lenta. Trata el tiempo de espera documentado por el remitente como un límite máximo, no como un objetivo. Normalmente, tu endpoint debe responder bastante antes de alcanzar ese límite.
El error de diseño más común es realizar todo el trabajo posterior antes de confirmar el webhook. Un controlador puede llamar secuencialmente a una base de datos, un sistema de gestión de pedidos, un servicio de notificaciones y una canalización de análisis. Una dependencia lenta puede hacer que el remitente vea un tiempo de espera aunque tu aplicación termine finalmente el trabajo. Entonces el remitente puede volver a intentarlo, creando un procesamiento duplicado o actualizaciones en conflicto.
Limita la ruta síncrona al trabajo necesario para tomar una decisión segura de aceptación. Esto suele incluir la autenticación de la solicitud, la validación básica del esquema, el almacenamiento duradero del evento y la publicación en la cola. Coloca el enriquecimiento costoso, las consultas a transportistas, la mensajería a clientes y las llamadas a API de terceros detrás de un worker. Supervisa por separado el tiempo dedicado a recibir, validar, persistir y confirmar el evento del tiempo dedicado a procesarlo.
Un tiempo de espera no equivale a una operación empresarial fallida. Desde la perspectiva del remitente, un tiempo de espera normalmente significa que no recibió una respuesta de éxito utilizable. Es posible que tu servicio haya almacenado correctamente el evento justo antes de que se cerrara la conexión. Por eso se requieren la idempotencia y la deduplicación incluso cuando el endpoint parece fiable.
¿Qué provoca los reintentos?
Un remitente de webhook puede volver a intentarlo después de un error de conexión, un tiempo de espera o una respuesta que su contrato clasifica como no exitosa. El calendario exacto, el número máximo de intentos, el algoritmo de espera progresiva y la ventana de entrega varían según el proveedor. No prometas un número fijo de reintentos a menos que esté indicado en la documentación del proveedor.
El receptor debe asumir que pueden producirse reintentos y diseñar el sistema deliberadamente para admitirlos:
- Utiliza un identificador de evento cuando esté disponible. Guárdalo con una restricción única o una clave de deduplicación equivalente.
- Haz que el procesamiento sea idempotente. Aplicar dos veces la misma actualización del estado de entrega no debe enviar dos mensajes al cliente, crear dos reembolsos ni avanzar incorrectamente un pedido.
- Conserva la carga útil original o un registro de auditoría útil. Esto facilita la reproducción, la investigación y la conciliación.
- Separa la aceptación del procesamiento. Un worker puede volver a intentar fallos internos sin obligar al remitente a repetir todo el intercambio HTTP.
- Registra los códigos de respuesta y la latencia. Un aumento de las respuestas 5xx, los tiempos de espera o los ID de eventos duplicados puede revelar una interrupción antes de que los usuarios informen de la falta de actualizaciones de seguimiento.
Por lo general, un evento duplicado debe recibir una respuesta exitosa si el evento original ya se aceptó de forma duradera. Devolver un error por cada duplicado puede activar reintentos innecesarios. El endpoint puede registrar que el evento ya se había visto, omitir la acción empresarial repetida y devolver la misma clase de éxito utilizada para un evento recién aceptado.
¿Cuándo debes devolver 4xx, 429 o 5xx?
Devuelve 4xx cuando sea poco probable que volver a intentar la misma solicitud solucione el problema. Algunos ejemplos son una firma no válida, la falta de autenticación obligatoria, una estructura de carga útil no compatible o una solicitud que infringe una regla de validación permanente. Antes de elegir 4xx, comprueba si el remitente considera ese estado un fallo permanente. Algunas plataformas tienen sus propias reglas para las entregas fallidas.
Utiliza 429 con cuidado. HTTP define 429 para los límites de frecuencia, y el encabezado Retry-After puede comunicar cuándo sería apropiado reintentar. Sin embargo, no todos los remitentes de webhooks interpretan 429 de la misma manera. Si tu cola está llena o tu servicio está sobrecargado, confirma que el proveedor volverá a intentarlo de forma segura y que su programación de reintentos no empeorará la sobrecarga. Una cola de entrada limitada y un plan de control de presión suelen ser mejores que permitir que las solicitudes fallen de forma impredecible.
Devuelve 5xx cuando el receptor no pueda aceptar el evento de forma segura debido a un problema temporal. Esto incluye una base de datos no disponible, un fallo al escribir en una cola duradera o un error interno que impidió la validación o la persistencia. Devolver 200 mientras se descarta silenciosamente el evento dificulta la recuperación porque el remitente no tiene motivos para volver a intentarlo.
Evita depender de redirecciones como 301, 302 o 307 para la entrega de webhooks. La gestión de redirecciones varía entre clientes, y redirigir una solicitud firmada puede generar ambigüedad sobre el destino, el método y el cuerpo. Configura el proveedor con el endpoint HTTPS final.
Una política de respuesta fiable para eventos de seguimiento
Para la mayoría de las integraciones de webhooks de seguimiento, la siguiente política es un punto de partida razonable:
- Devuelve
200o202después de que el evento haya superado la autenticación y se haya almacenado de forma duradera o colocado en una cola fiable. - Devuelve una respuesta 4xx para una firma no válida, una autenticación no válida o una carga útil permanentemente inutilizable, siguiendo las reglas documentadas del proveedor.
- Devuelve 5xx cuando un fallo temporal impida la aceptación duradera.
- Devuelve una respuesta exitosa para un duplicado reconocido de forma segura, evitando al mismo tiempo efectos empresariales duplicados.
- Mantén el controlador rápido y mide su latencia de confirmación.
- Prueba los escenarios de tiempo de espera, reintento, duplicado, desorden, formato incorrecto e interrupción del proveedor antes del lanzamiento en producción.
Si estás integrando una API de seguimiento, comienza con la documentación del webhook del proveedor y confirma los códigos de éxito aceptados, el método de firma de solicitudes, el tiempo de espera, los activadores de reintento, el esquema de la carga útil y el identificador del evento. Para las integraciones de 17TRACK, la documentación oficial de Tracking API es el lugar adecuado para verificar el contrato específico del proveedor en lugar de inferirlo a partir de la práctica HTTP general.
Lista de comprobación de implementación
- El endpoint es accesible a través de HTTPS y tiene una URL de producción estable.
- La autenticación y la verificación de la firma se realizan antes del procesamiento empresarial.
- La solicitud sin procesar o una representación verificable se conserva cuando es necesario para las comprobaciones de firma y la resolución de problemas.
- El evento se persiste antes de enviar la respuesta de éxito.
- Las entregas duplicadas son seguras y no repiten acciones irreversibles.
- Los workers pueden volver a intentar el procesamiento interno independientemente del ciclo de reintentos HTTP del remitente.
- Los registros incluyen el ID del evento, la hora de entrega, el código de respuesta, el estado del procesamiento y el ID de correlación sin exponer secretos.
- Las alertas distinguen entre tiempos de espera del endpoint, fallos de validación 4xx, interrupciones 5xx, retrasos de la cola y entregas duplicadas.
- El comportamiento documentado del proveedor se ha probado con eventos reales o de prueba.
Preguntas frecuentes
¿Es 200 OK mejor que 202 Accepted para un webhook?
Ninguno es universalmente mejor. Utiliza 200 OK cuando la solicitud se haya aceptado y tu integración trate la respuesta como un éxito general. Utiliza 202 Accepted cuando el evento se haya aceptado para un procesamiento asíncrono. Confirma que el remitente clasifica la respuesta 2xx elegida como exitosa.
¿Debe un endpoint de webhook esperar hasta que la actualización del seguimiento se procese por completo?
Por lo general, no. Solo debe esperar hasta que el evento se autentique, valide y acepte de forma duradera. El trabajo de larga duración normalmente debe realizarse después de la confirmación para que una dependencia lenta no provoque un tiempo de espera y un reintento evitables.
¿Qué debe ocurrir cuando el mismo evento de seguimiento llega dos veces?
Reconócelo utilizando el ID del evento del proveedor o una clave equivalente cuidadosamente diseñada, omite los efectos secundarios duplicados y devuelve una respuesta exitosa si el evento ya había sido aceptado. Esto hace que los reintentos sean seguros sin ocultar nuevos fallos de procesamiento.
¿Una firma no válida debe devolver 400 o 401?
La elección depende de tu modelo de autenticación y de las expectativas documentadas del proveedor. Ambos pueden comunicar un rechazo, pero la coherencia es más importante que seleccionar uno universalmente. No confirmes un evento cuya autenticidad no puedas verificar.
¿Una respuesta 5xx siempre provoca un reintento?
No. Muchos sistemas de webhook vuelven a intentar las solicitudes que agotan el tiempo de espera y los errores del servidor, pero los activadores y calendarios de reintento son específicos de cada proveedor. Trata los reintentos como un comportamiento de integración documentado y verifícalos en un entorno de prueba.
Fuentes
- RFC 9110: Semántica HTTP — definiciones de respuestas exitosas, errores del cliente, errores del servidor, redirecciones y gestión de respuestas.
- RFC 6585: Códigos de estado HTTP adicionales — especificación de
429 Too Many Requests. - Documentación de Stripe Webhooks — orientación práctica sobre respuestas de webhooks, procesamiento asíncrono y gestión de eventos duplicados.
- Documentación de GitHub: Gestión de entregas de webhooks — inspección de entregas y consideraciones operativas para integraciones de webhooks.
- Documentación de 17TRACK Tracking API — documentación específica del proveedor que debe consultarse al implementar integraciones de Tracking API.


