¿Qué es un webhook? Definición, seguridad y reintentos

¿Qué es un webhook?

Un webhook es una petición HTTP, casi siempre un POST, que un servicio envía a una URL que registraste cuando algo ocurre de su lado. Le das tu URL al proveedor una sola vez. Después te llama con un pequeño payload JSON cada vez que sucede un evento, como un pago completado o una compilación terminada. Nunca tienes que preguntar "¿hay novedades?".

Webhooks frente a polling

Sin webhooks haces polling: tu código llama a la API del proveedor cada cierto tiempo y busca cambios. Eso tiene tres costes.

• Retraso. Con un intervalo de 60 segundos, un evento espera 30 segundos de media antes de que lo notes.
• Desperdicio. La mayoría de las consultas no devuelven nada nuevo, pero consumen ancho de banda y cuentan para los límites de tasa del proveedor (consulta por qué las APIs limitan la tasa, en inglés).
• Disyuntiva. Si consultas más rápido, chocas con los límites; si consultas más despacio, reaccionas tarde.

Un webhook lo invierte: quien sabe que el evento ocurrió te avisa al instante.

Cómo funciona la entrega de un webhook

1. Registras una URL HTTPS en el proveedor, normalmente en una página de ajustes.
2. Ocurre un evento: un cliente paga, se fusiona un pull request, falla un monitor.
3. El proveedor construye un payload, por ejemplo {"event": "charge.succeeded", "data": {"id": "ch_123", "amount": 1500}}, y lo envía por POST a tu URL con cabeceras como el tipo de evento, un ID de entrega y una firma.
4. Tu endpoint verifica la petición, guarda o encola el evento y responde con un estado 2xx.
5. Si responde con un error o no responde, el proveedor reintenta más tarde.

Verifica cada webhook

Cualquiera que conozca tu URL puede enviarle un POST, así que un handler sin verificar puede engañarse para marcar pedidos como pagados o conceder acceso. La defensa habitual es una firma HMAC: el proveedor firma el cuerpo exacto de la petición con un secreto compartido (HMAC se define en el RFC 2104) y envía el resultado en una cabecera. Tú lo recalculas y rechazas lo que no coincida. Stripe usa la cabecera Stripe-Signature y sus librerías rechazan por defecto marcas de tiempo de más de 5 minutos, lo que evita los replays.

Dos detalles causan la mayoría de los fallos. Primero, comprobar la firma exige el cuerpo sin procesar, así que no dejes que tu framework parsee y vuelva a serializar el JSON antes de verificar. Segundo, compara las firmas en tiempo constante. Un bearer token estático en una cabecera es más débil, porque una sola petición capturada se puede reenviar. Una lista de IPs permitidas ayuda como capa extra, pero se rompe cuando el proveedor cambia de direcciones.

Reintentos, duplicados y orden

La entrega es al menos una vez, no exactamente una. Stripe reintenta un evento fallido hasta tres días en modo live, y GitHub espera una respuesta 2xx en 10 segundos. Por eso tu handler verá duplicados y, a veces, eventos desordenados (Stripe no garantiza el orden).

• Haz los handlers idempotentes. Guarda el ID del evento o de la entrega y omite los ya procesados.
• Confirma rápido, trabaja después. Guarda el evento, devuelve 200 y procésalo desde una cola.
• No confíes en el orden. Si order.fulfilled llega antes que order.created, consulta el objeto actual en la API en lugar de fiarte de la secuencia.

Errores comunes con webhooks

• Saltarse la verificación de la firma porque "nadie conoce la URL".
• Parsear el cuerpo antes de verificar, de modo que la firma nunca coincide.
• Hacer trabajo lento dentro de la petición, lo que provoca timeouts y luego reintentos duplicados.
• Devolver 200 aunque falle el guardado del evento, así que el proveedor nunca reintenta.
• Probar solo en localhost. Usa un túnel o la CLI del proveedor para reenviar eventos reales, y repite uno con curl para comprobar tu handler.
• No mirar nunca el registro de entregas del proveedor, así que los fallos pasan desapercibidos.

Webhooks en monitorización

Los webhooks son la forma en que los monitores pasan una alerta a tus propias herramientas. En la monitorización de APIs de LoadFocus, un canal de alertas por webhook envía un POST HTTP con cuerpo JSON a una URL HTTPS que controlas cuando un check falla, se recupera, funciona degradado o un certificado SSL está a punto de caducar. El payload incluye campos como event (por ejemplo check.failed), el nombre y la URL del check, el estado, la ubicación y una marca de tiempo. Tu endpoint debe devolver un 2xx rápido. Al guardar el canal se envía un POST de confirmación único, y los pasos de configuración están en la documentación del canal de alertas por webhook (en inglés). Mantén la URL receptora difícil de adivinar y comprueba los campos del payload antes de actuar. Para el contexto general, mira monitorización de APIs.

Preguntas frecuentes: webhooks

¿Un webhook es lo mismo que una URL de callback?

Sí. Webhook, callback HTTP y reverse API describen el mismo patrón: un servicio llama a una URL que le diste cuando ocurre un evento.

¿Qué diferencia hay entre webhooks y WebSockets?

Un webhook es una petición HTTP puntual que envía un proveedor cuando ocurre un evento. Un WebSocket es una conexión bidireccional duradera entre cliente y servidor. Usa webhooks para eventos ocasionales entre servicios y WebSockets para tráfico bidireccional constante, como un chat.

¿Qué pasa si mi endpoint está caído?

La mayoría de los proveedores reintentan durante un tiempo y luego se rinden. Stripe, por ejemplo, reintenta hasta tres días en modo live. Después tendrás que reenviar los eventos tú mismo, así que vigila el registro de entregas del proveedor y ten una forma de volver a consultar los eventos perdidos.

¿Cómo pruebo un handler de webhooks en local?

Los proveedores no llegan a localhost, así que expónlo con un túnel como ngrok o usa la CLI del proveedor para reenviar eventos, como hace la CLI de Stripe. Después repite payloads guardados con curl mientras depuras.

¿Webhooks o polling?

Webhooks cuando importa la latencia o los eventos son poco frecuentes. Polling para sincronizaciones masivas o cuando no puedes exponer un endpoint HTTPS público. Muchas integraciones combinan ambos: webhooks para la rapidez y una consulta ocasional para recoger lo que se haya perdido.