¿Qué es un Webhook y para Qué Sirve? Explicación y Ejemplos
Descubre cómo funcionan los Webhooks impulsados por eventos (Event-Driven), sus diferencias frente al sondeo HTTP, cómo validar firmas criptográficas HMAC y cómo procesarlos en un servidor.
Un Webhook es un mecanismo de comunicación automatizada basado en eventos en el que una aplicación envía una notificación HTTP POST en tiempo real con datos hacia otra aplicación tan pronto como ocurre un suceso específico.
Elimina la necesidad de realizar sondeos continuos (polling) preguntando al servidor cada segundo si hubo novedades, ahorrando ancho de banda, CPU y garantizando latencia casi nula en notificaciones críticas como pagos o despliegues.
Imagina pedir un paquete a domicilio: el sondeo continuo (polling) sería llamar al repartidor cada dos minutos para preguntarle '¿ya llegaste?'; un Webhook es el timbre de tu casa: te quedas haciendo tus actividades tranquilamente y solo atiendes cuando el timbre suena anunciando que el paquete está en la puerta.
Explicación Paso a Paso del Tema
Configurar un endpoint receptor de eventos
Habilita una ruta en tu servidor Backend que acepte peticiones HTTP con método POST.
El emisor del webhook (por ejemplo GitHub, Stripe o Shopify) requiere registrar una URL pública (ej. `https://miempresa.com/api/webhooks/github`). Tu servidor debe recibir el cuerpo JSON en bruto (raw body) para poder verificar firmas y responder de inmediato con un código 200 OK.
app.post('/api/webhook', express.raw({ type: 'application/json' }), (req, res) => { res.status(200).send('OK'); });| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| app.post | Método de enrutador | Define que la ruta solo responderá a peticiones HTTP POST |
| express.raw() | Middleware | Conserva el payload sin parsear como buffer para validar la firma criptográfica con exactitud de bytes |
| res.status(200) | Confirmación HTTP | Acuse de recibo inmediato para evitar que el emisor asuma timeout y reintente el envío |
Responde con 200 OK en menos de 500ms y envía la carga útil a una cola de mensajes en segundo plano (como Redis BullMQ o AWS SQS) para procesar el trabajo asíncronamente.
Tardar demasiado tiempo en procesar tareas pesadas (como enviar correos o generar PDFs) antes de responder al webhook, provocando que el emisor corte la conexión por timeout (5 a 10s) y reenvíe el evento múltiples veces.
Verificar la firma de seguridad criptográfica (HMAC)
Valida que el webhook provenga verdaderamente del proveedor y que nadie haya alterado el contenido.
El proveedor genera un hash HMAC-SHA256 usando el cuerpo en crudo de la petición y un secreto que solo tú y él conocen, enviándolo en una cabecera como `X-Signature`. En tu servidor, calculas el mismo hash con tu secreto y comparas ambos resultados. Si no coinciden, rechazas la petición con 401 Unauthorized.
crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex') === headerSignature| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| createHmac | Función criptográfica | Algoritmo de autenticación de mensajes basado en hash |
| crypto.timingSafeEqual | Comparación segura | Compara buffers evitando ataques de canal lateral por análisis de tiempos de ejecución |
Usa siempre las bibliotecas oficiales SDK del proveedor (ej. `stripe.webhooks.constructEvent()`) para evitar errores sutiles de serialización al verificar la firma.
Confiar a ciegas en cualquier petición que llegue a la ruta pública de tu webhook sin verificar la firma ni validar una lista de IPs permitidas.
Garantizar la idempotencia ante eventos duplicados
Prevé que el proveedor de webhooks puede reenviar un mismo evento debido a microcortes de red.
La mayoría de los sistemas emisores garantizan una entrega de tipo 'al menos una vez' (at-least-once delivery). Si la conexión parpadea justo después de que recibiste el evento pero antes de que tu respuesta 200 llegara de regreso, el emisor lo enviará de nuevo. Tu sistema debe registrar el identificador del evento (ej. `event_id`) en la base de datos y descartar procesarlo si ya fue ejecutado previamente.
INSERT INTO webhooks_procesados (event_id, fecha) VALUES ('evt_1928301', NOW()) ON CONFLICT DO NOTHING;| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| event_id | Clave primaria única | Identificador inequívoco proporcionado por el emisor para cada suceso |
| ON CONFLICT DO NOTHING | Cláusula SQL | Evita duplicados si el evento ya existe sin romper la ejecución del programa |
Crea una tabla en tu base de datos dedicada exclusivamente al registro de identificadores de webhooks procesados con un índice único.
Acreditar dos veces saldo o despachar dos veces un pedido a un usuario porque el webhook de confirmación de pago se recibió dos veces.
Casos Prácticos Reales en Producción
Situaciones de ingeniería reales sin mención de presupuestos ficticios.
1Caso de Producción: Automatización de Despliegues Continuos con Webhooks de GitHub
Un equipo de desarrollo dependía de que un administrador de sistemas ingresara manualmente por SSH a los servidores cada vez que alguien hacía un merge a la rama principal para hacer git pull y compilar la app.
Se configuró un Webhook en el repositorio de GitHub que emite un POST hacia el servidor de integración continua ante el evento 'push'. El servidor verifica la firma secreta de GitHub y activa inmediatamente una pipeline de pruebas y despliegue sin intervención humana.
Fichas Nemotécnicas de Conceptos Clave
Glosario rápido para recordar los términos fundamentales de la lección.
Técnica tradicional ineficiente donde el cliente consulta repetidamente a intervalos regulares si hay nueva información disponible.
Llamada HTTP POST originada por el servidor emisor hacia una URL pública configurada por el receptor cuando se dispara un evento.
Hash criptográfico generado con un secreto compartido que viaja en las cabeceras para validar que el webhook proviene legítimamente del emisor y no fue alterado.
¿Qué es un Webhook y para Qué Sirve? Explicación y Ejemplos
Selecciona una opción para autoevaluarte al instante. La respuesta se califica de inmediato.
¿Cuál es la principal ventaja de un Webhook frente a la técnica de Sondeo (Polling)?
¿Por qué es crucial implementar idempotencia al procesar Webhooks?
¿Qué método HTTP se utiliza de forma estándar para transmitir la carga útil de un Webhook?
Preguntas Frecuentes (FAQ)
¿Cómo puedo probar un Webhook en mi computadora si localhost no tiene IP pública?
Puedes usar herramientas de túnel seguro como ngrok, Cloudflare Tunnels o Localtunnel. Te otorgan una URL pública HTTPS temporal que redirige el tráfico directamente al puerto donde corre tu servidor local.
¿Qué ocurre si mi servidor está caído cuando el emisor envía el Webhook?
Los proveedores formales aplican políticas de reintentos exponenciales (backoff). Reintentan el envío a los 5 minutos, 30 minutos, 2 horas, etc., hasta por 24 o 72 horas antes de marcar el endpoint como fallido.
¿Cuál es la diferencia entre un Webhook y un WebSocket?
Un Webhook es una petición HTTP puntual e independiente servidor a servidor activada por eventos. Un WebSocket es una conexión TCP persistente y bidireccional continua típicamente entre el navegador y el servidor para chats o juegos en vivo.