Webhook explicado: cómo avisan las apps cuando algo pasa (con video)

Imagina que esperas un paquete. Podrías pararte en la puerta y salir a mirar la calle cada cinco segundos, todo el día, por si el camión pasa. O podrías instalar un timbre y dedicarte a tu vida: cuando el paquete llegue, alguien toca y tú sales.

Esa diferencia — salir a mirar cada cinco segundos versus que te avisen — es exactamente la diferencia entre polling y webhook, y es una de las piezas más importantes de internet moderna. En este post te la explico a fondo: cómo funciona, con un ejemplo de datos real, en qué se diferencia de un WebSocket, y las cosas que nadie te cuenta hasta que un webhook te falla en producción.

Y si prefieres la versión hablada, al final del post está el video de la serie (este es el segundo — el primero fue WebSocket).

El problema: preguntar sin parar

Muchas apps funcionan con un patrón que se llama polling: cada cierto tiempo, el cliente le pregunta al servidor "¿hay algo nuevo?" y el servidor responde. La mayoría de las veces, la respuesta es no.

Ese ciclo tiene tres costos que se pagan siempre, haya noticias o no:

• Latencia: si preguntas cada 5 segundos, en promedio te enteras de las cosas 2.5 segundos tarde. Para una lista de precios da igual; para un mensaje de un cliente, se siente roto.
• Tráfico inútil: estás pagando ancho de banda y procesamiento para transmitir silencio. Si 10.000 clientes preguntan cada 5 segundos, son 2.000 preguntas por segundo... para terminar casi siempre en "nada nuevo".
• Carga del servidor: tu backend trabaja sin parar respondiendo preguntas cuya respuesta, el 99% de las veces, ya conocía.

Y hay algo peor: el polling solo funciona mientras tu app está corriendo y preguntando. Si el proceso se cae, las preguntas se detienen y los eventos que pasaron mientras nadie preguntaba simplemente se pierden.

La idea del webhook: invertir la dirección

Un webhook le da la vuelta al problema. En lugar de que tú preguntes todo el tiempo, le dices al otro servicio: "cuando pase algo, avísame tú — manda la información a esta URL".

Por eso la metáfora exacta es un timbre: no tocas la puerta cada cinco segundos; dejas tu dirección y el cartero toca cuando el paquete llega. La comunicación se invierte: ya no es el cliente tirando de la información, es el servicio empujando el dato justo cuando ocurre.

Técnicamente, un webhook no es un protocolo nuevo ni tecnología exótica: es una petición HTTP normal — casi siempre un POST — que un servicio te envía a una URL tuya cuando sucede un evento. Toda la "magia" es una inversión de roles: tu servidor, que normalmente responde peticiones, esta vez las recibe.

Cómo funciona, paso a paso

El flujo completo tiene tres pasos:

1. Registras tu URL. En el servicio externo (WhatsApp, Stripe, GitHub, tu pasarela de pagos...) configuras a qué URL quiere que avise: por ejemplo https://tuapp.com/api/webhooks/whatsapp. Muchos servicios también te dan un secreto en ese momento — luego veremos para qué sirve.

2. Algo pasa del otro lado. Un cliente escribe a tu número de WhatsApp, alguien compra con su tarjeta, se abre un pull request. El servicio detecta el evento.

3. Te llega un POST con los datos. El servicio arma un JSON con la información del evento y la manda a tu URL. Por ejemplo, cuando un mensaje llega a un número de WhatsApp Business, el webhook de la Cloud API se ve más o menos así (simplificado):

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "51987654321",
          "text": { "body": "¿Tienen turno para mañana?" },
          "type": "text",
          "id": "wamid.HBgMNzk4Nz...",
          "timestamp": "1728403200"
        }]
      }
    }]
  }]
}

Tu servidor recibe ese POST, lo procesa y reacciona: guarda el mensaje en la base de datos, despierta al bot para que responda, actualiza un dashboard, manda una notificación interna. Lo que necesites.

Dos detalles que valen oro:

• El aviso incluye los datos. No es solo "pasó algo" — el POST trae la información completa del evento. No tienes que volver a preguntar qué pasó.
• Es una URL tuya, en tu servidor. El servicio no necesita saber nada de tu tecnología: le da igual si tu backend es Node, Python o Go. HTTP es el contrato.

Webhook vs. WebSocket vs. polling: cuándo usar cada uno

Si leíste el post anterior de la serie, te estarás preguntando: ¿y en qué se diferencia esto de un WebSocket? Los tres resuelven el mismo problema de fondo — enterarte rápido — pero de formas distintas:

Mecanismo	Cómo te enteras	Ideal para
Polling	Preguntas cada X segundos	Datos que cambian despacio; casos simples sin infraestructura
Webhook	El servicio te hace un POST puntual por cada evento	Integraciones entre servicios: pagos, mensajes, deploys, envíos
WebSocket	Un canal queda abierto y ambos lados escriben cuando quieren	Comunicación en vivo dentro de tu app: chat, presencia, cotizaciones

La regla práctica: el webhook conecta servicios (de tu servidor hacia afuera, evento a evento), mientras que el WebSocket conecta tu app con cada usuario en una sesión continua. No compiten — de hecho, en muchos productos trabajan juntos, como veremos abajo.

Lo que nadie te cuenta: la vida en producción

Configurar un webhook toma cinco minutos. Hacerlo serio toma un poco más. Cuatro cosas que solo aprendes cuando un webhook te falla un viernes:

1. Responde rápido, procesa después. El servicio que te avisa espera tu 200 OK, y no espera para siempre: si tu endpoint tarda demasiado en contestar, el aviso se marca como fallido y llega el reintento — con tu servidor todavía ocupado procesando el primer intento. La regla es separar las dos cosas: acknowledgar al instante (guardar el evento en una cola) y procesarlo en segundo plano. Responder rápido y hacer el trabajo pesado en la misma request es la receta clásica del webhook que se cuelga.

2. Verifica que el aviso es de verdad. Tu URL es pública: cualquiera que la descubra puede mandarte un POST falso con un "pago confirmado" que nunca existió. Por eso los servicios te dan un secreto al registrar el webhook: cada aviso viaja firmado (normalmente con un HMAC en un header), y tu servidor debe recalcular esa firma con el secreto antes de creer una sola letra del payload. Sin verificación de firma, tu webhook es una puerta abierta.

3. Los reintentos van a duplicar tus eventos. Si tu servidor no responde 200 a tiempo (o responde un error), el servicio reintenta el envío — a veces durante horas. Eso significa que el mismo evento puede llegar dos o tres veces. Tu endpoint tiene que estar preparado: si el mismo mensaje de WhatsApp llega dos veces, el cliente debe recibir una respuesta, no dos. Eso se resuelve con idempotencia: identificar cada evento (los servicios suelen incluir un ID único) y descartar los que ya procesaste.

4. HTTPS obligatorio y secretos fuera de la URL. El endpoint del webhook debe ser HTTPS (los datos viajan por internet), y el secreto o token de verificación va en headers, nunca como parámetro en la URL — las URLs quedan registradas en logs por todas partes.

Un caso real: cada mensaje de un chatbot entra por un webhook

Esto no es teoría lejana: si hablaste con un bot de WhatsApp — de los nuestros o de cualquiera — cada uno de tus mensajes entró por un webhook.

En UseFlowy, el flujo es exactamente el patrón de arriba, pulido con las lecciones que fuimos aprendiendo:

1. Escribes a un bot en WhatsApp y Meta (la Cloud API de WhatsApp) hace un POST a nuestro webhook con tu mensaje.
2. Respondemos 200 de inmediato y el mensaje entra a una cola — el procesamiento pesado nunca bloquea el aviso.
3. La cola despierta al engine del bot, que decide si responde el flujo o la IA (y si hay RAG de por medio, busca primero en los documentos del negocio).
4. La respuesta sale hacia WhatsApp como una llamada de API normal — y de vuelta hacia ti, que la ves en el chat en segundos.

¿Y el punto 3 de la lista de arriba (los duplicados)? Lo vivimos en carne propia: implementamos idempotencia por mensaje — cada mensaje tiene un ID único y si el mismo webhook llega repetido, se descarta en vez de generar un segundo turno. Un mensaje del cliente, una respuesta del bot. Sin esa pieza, cada reconnect de red de WhatsApp duplicaría conversaciones enteras.

Y no solo WhatsApp: cuando un negocio paga su suscripción en UseFlowy, la confirmación del pago también llega como webhook de nuestra pasarela (Culqi). El mismo patrón — registro, evento, POST firmado, idempotencia — gobierna desde el aviso de "pagaste" hasta el "te escribió un cliente".

Lo vemos en video

Grabamos un video corto (2 minutos) recorriendo todo esto con animaciones: el problema del polling, la metáfora del timbre, el flujo técnico con el JSON en pantalla y los casos de uso:

👉 ¿Qué es un Webhook? Explicado simple

En resumen

• Polling es preguntar sin parar: pagas latencia, tráfico y carga para enterarte tarde.
• Un webhook invierte la dirección: registras tu URL y el servicio te hace un POST con los datos justo cuando el evento ocurre.
• Es HTTP de toda la vida — no hay protocolo nuevo que aprender, solo una inversión de roles.
• Webhook conecta servicios (evento a evento); WebSocket mantiene un canal en vivo con cada usuario.
• En producción lo serio no es recibir el POST: es responder rápido, verificar la firma y sobrevivir a los reintentos con idempotencia.

Si tienes un negocio que atiende clientes por WhatsApp, todo esto trabaja para ti sin que lo toques: cada mensaje que te escriben entra por un webhook verificado, con idempotencia y en cola — y el bot responde en segundos. Crea tu bot gratis y conéctalo a tu WhatsApp en minutos.

---

Esta es la parte 2 de la serie. Si te perdiste la primera: WebSocket explicado. Y en la parte 3 explicamos RAG — cómo logramos que un bot responda con la información real de tu negocio.