Programación · conceptos · web

¿Qué es un webhook?

Configuras un pago y tu aplicación reacciona en el instante en que el dinero se cobra. Subes un commit y un build arranca solo. Detrás de esa inmediatez casi siempre hay un webhook. Esta guía explica, con claridad, qué es un webhook, en qué se diferencia de una llamada a una API normal, cómo recibirlo de forma segura, y dónde ya dependes de ellos.

La definición corta

Un webhook es una petición HTTP automática que un servicio envía a una URL que tú controlas cuando ocurre un evento. En lugar de pedir novedades a un servicio, es él quien te avisa en cuanto las hay.

Por eso se le llama «API inversa». Con una API normal, tú eres el cliente: haces la petición y el servidor responde. Con un webhook los papeles se invierten — el proveedor pasa a ser el cliente y tu endpoint es el servidor al que llama.

Webhook vs sondear una API

Antes de los webhooks, la forma habitual de estar al día era el sondeo: llamar a una API en un temporizador («¿algo nuevo?») una y otra vez. Es simple pero derrochador — la mayoría de las llamadas no devuelven nada, y siempre hay un desfase entre el evento y la siguiente comprobación.

• Sondeo — preguntas en bucle. Muchas peticiones inútiles, reacción retrasada, fácil de construir.
• Webhook — el servicio te avisa una vez, de inmediato. Eficiente y casi en tiempo real, pero debes tener un endpoint para recibirlo.

Cómo funciona, paso a paso

1. Registras una URL (tu endpoint) con el proveedor y eliges qué eventos te importan.
2. Cuando ocurre tal evento, el proveedor envía un POST HTTP a tu URL con un cuerpo (normalmente JSON) que lo describe.
3. Tu servidor lee el contenido, devuelve rápido un estado 2xx para acusarlo, y hace el trabajo real después.
4. Si tu endpoint está caído o devuelve un error, la mayoría de los proveedores reintentan con backoff — de ahí los posibles duplicados.

Una entrega se parece a cualquier petición HTTP:

POST /webhooks/payments  HTTP/1.1
Host: tuapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Ejemplos que ya has visto

• Pagos — Stripe y PayPal envían un webhook cuando un cobro tiene éxito, falla o se reembolsa, para que tu app actualice el pedido sin sondeo.
• Hospedaje de código — GitHub y GitLab disparan un webhook en push, pull request o issue: así se activan builds de CI y bots.
• Mensajería — Slack, Discord y las plataformas de chat usan webhooks entrantes para publicar mensajes y notificar a tu app.

Recibirlo de forma segura

Un receptor robusto hace cuatro cosas:

• Servir HTTPS y aceptar POST; responder rápido con un 2xx, luego procesar de forma asíncrona.
• Verificar la firma — los proveedores firman el cuerpo (un HMAC con un secreto compartido). Rechaza lo que falle.
• Ser idempotente — el mismo evento puede llegar más de una vez; usa el id del evento para que la reentrega sea inofensiva.
• Devolver errores con honestidad — si no puedes procesarlo, devuelve un no-2xx para que el proveedor reintente en vez de descartarlo.

Los webhooks necesitan un endpoint siempre en línea con una URL HTTPS pública — por eso un pequeño servidor o instancia cloud es el hogar habitual de un receptor de webhooks, en lugar de una máquina que se duerme.

Preguntas frecuentes

¿Qué es un webhook en términos simples?

Un webhook es un mensaje automático que un servicio envía a una URL que tú controlas en el momento en que ocurre algo — por ejemplo «un pago tuvo éxito» o «se subió un commit». En lugar de preguntar al servicio una y otra vez «¿algo nuevo?» (sondear su API), el servicio te llama con una petición HTTP POST en cuanto ocurre el evento. Suele describirse como una «API inversa»: con una API normal tú haces la petición; con un webhook el servicio te la hace a ti.

¿Cuál es la diferencia entre un webhook y una API?

Están relacionados pero apuntan en sentidos opuestos. Con una API (REST) normal envías una petición al proveedor cuando quieres datos, y responde. Con un webhook el proveedor envía una petición a tu servidor cuando ocurre un evento, así recibes los datos casi en tiempo real sin pedirlos. Un webhook usa la misma mecánica HTTP que una API — es el proveedor actuando como cliente y tu endpoint como servidor.

¿Por qué usar un webhook en vez de sondeo?

El sondeo (polling) consiste en llamar a una API en un temporizador para comprobar cambios, lo que desperdicia peticiones y añade retraso entre el evento y tu reacción. Los webhooks te empujan el evento en el momento en que ocurre, así que son más eficientes y mucho más cercanos al tiempo real. La contrapartida es que debes tener un endpoint siempre en línea, y manejar reintentos y entregas duplicadas.

¿Cómo recibo un webhook de forma segura?

Expón un endpoint HTTPS que acepte POST, devuelve rápido un estado 2xx para acusar recibo, y procesa el trabajo de forma asíncrona. Verifica la firma que envía el proveedor (un HMAC del cuerpo con un secreto compartido) para saber que la petición es auténtica, y haz el manejo idempotente porque un mismo evento puede entregarse más de una vez. Rechaza todo lo que falle la verificación de firma.

En resumen

Un webhook es la forma que tiene la web de decir «no nos llames, ya te llamamos nosotros»: una petición HTTP automática que un servicio envía a tu endpoint en cuanto ocurre un evento. Es más eficiente y mucho más en tiempo real que sondear una API — a costa de mantener un endpoint fiable, que verifica firmas, para recibirlo. Una vez que los ves, notarás webhooks detrás de casi cada «se actualizó solo» del software moderno.