Qué es un webhook y cómo funciona

Un webhook es la forma más simple que tiene un sistema de avisarle a otro que algo pasó: en lugar de preguntar cada tanto si hay novedades, el servicio envía una solicitud HTTP a tu aplicación en el momento exacto en que ocurre el evento. En esta guía vas a entender cómo funciona por dentro, cuándo usarlo (y cuándo no) y qué necesita una implementación seria.

La analogía del timbre

Imagina que pediste un paquete. Hay dos formas de saber si llegó: abrir la puerta cada cinco minutos para revisar, o instalar un timbre y dejar que el repartidor lo toque cuando llegue. Consultar una API repetidamente (polling) es abrir la puerta cada cinco minutos. El webhook es el timbre: tú informas una dirección y el otro lado se encarga de avisarte.

Técnicamente, un webhook es una solicitud HTTP — casi siempre un POST con cuerpo JSON — que un proveedor (Stripe, GitHub, Mercado Pago, Shopify…) envía a una URL que tú registraste. Esa URL es un endpoint de tu aplicación, público en internet, preparado para recibir y procesar esos avisos.

Cómo funciona un webhook, paso a paso

Registras una URL en el panel o en la API del proveedor — por ejemplo, https://tu-app.com/webhooks/pagos — y eliges qué eventos quieres recibir (pago aprobado, pedido creado, push al repositorio…).
El evento ocurre del lado del proveedor: un cliente paga una factura, se confirma una transferencia Pix, alguien abre un pull request.
El proveedor arma un payload — un JSON que describe el evento — y envía un POST a tu URL, generalmente con headers de identificación y una firma criptográfica.
Tu aplicación responde con un estado 2xx para confirmar la recepción. Cualquier otra respuesta (o una demora) se trata como falla.
Si la entrega falla, el proveedor reintenta — normalmente con intervalos crecientes (backoff exponencial) durante horas o días.

Un ejemplo real de payload

La estructura varía según el proveedor, pero casi todos siguen el mismo patrón de envelope: un identificador del evento, el tipo, la fecha y los datos en sí. Un webhook de pago típico se ve así:

POST /webhooks/pagos · application/json

{
  "id": "evt_1QxK2mLkdIwHu7ix",
  "type": "payment.approved",
  "created_at": "2026-07-25T14:32:07Z",
  "data": {
    "payment_id": "pay_9f8e7d6c",
    "amount": 14990,
    "currency": "BRL",
    "method": "pix",
    "customer_email": "cliente@ejemplo.com"
  }
}

Fíjate en dos detalles que aparecen en prácticamente todo proveedor serio: el id del evento (que permite detectar duplicados) y el type (que permite enrutar el procesamiento). Los headers que acompañan esa solicitud — firma, identificador de entrega, content-type — merecen un capítulo propio: lo diseccionamos todo en Anatomía de una solicitud de webhook.

Webhook vs. API: ¿cuál es la diferencia?

El webhook no sustituye a la API — los dos se complementan, y lo que cambia es la dirección de la comunicación. En la API, tú preguntas; en el webhook, ellos te avisan.

	API (polling)	Webhook
Dirección	Tu aplicación consulta al proveedor	El proveedor llama a tu aplicación
Latencia	Depende del intervalo de consulta (segundos a minutos)	Casi en tiempo real (milisegundos después del evento)
Costo	Consultas repetidas, la mayoría sin novedades	Una solicitud por evento
Infraestructura	Basta con un job programado	Exige endpoint público, reintentos e idempotencia
Uso típico	Buscar datos bajo demanda, reconciliación	Reaccionar a eventos: pagos, deploys, mensajes

Una arquitectura madura suele usar ambos: webhooks para reaccionar rápido y una rutina de reconciliación vía API (por ejemplo, cada hora) para cubrir cualquier evento que se pierda en el camino.

Dónde aparecen los webhooks en el día a día

Pagos — Stripe, Mercado Pago, PagSeguro y similares avisan cuando se confirma una transferencia Pix, se rechaza una tarjeta o se cancela una suscripción.
Git y CI/CD — GitHub y GitLab disparan webhooks con cada push, pull request o release, y así es como arrancan los pipelines de deploy.
Mensajería — WhatsApp Business, Telegram y Slack entregan los mensajes recibidos vía webhook.
Infoproductos y e-commerce — Hotmart, Kiwify y Shopify notifican ventas, reembolsos y cambios de estado de los pedidos.
Automatización — Zapier, Make y n8n son, en esencia, enrutadores de webhooks entre servicios.

Qué necesita una implementación seria

Recibir un POST es fácil; operar webhooks en producción con confiabilidad es donde vive la complejidad. Los puntos esenciales:

Responde rápido, procesa después. Confirma con 200 en milisegundos y manda el trabajo pesado a una cola. Los proveedores suelen tener timeouts de 5 a 30 segundos — si te pasas, cuenta como falla y llega el reintento.
Sé idempotente. Los reintentos garantizan entrega al menos una vez, lo que significa que el mismo evento puede llegar dos veces. Guarda el id del evento e ignora los duplicados.
Valida la firma. Tu endpoint es público; cualquiera puede enviarle un POST. La firma HMAC es lo que separa un evento legítimo de uno falsificado — explicamos el mecanismo completo en Seguridad de webhooks: firma HMAC y buenas prácticas.
No confíes en el orden. Un reintento puede hacer que el evento "creado" llegue después del "actualizado". Usa el timestamp del evento (o consulta la API) como fuente de verdad del estado actual.
Monitorea y ten replay. Las fallas silenciosas de webhooks son célebres: todo parece funcionar hasta que alguien nota que los pedidos dejaron de caer en el sistema. Registra cada entrega y ten cómo reprocesar.

Cómo empezar a experimentar

La mejor forma de entender los webhooks es ver llegar uno. El camino más corto: apunta el webhook de prueba del proveedor a un endpoint de inspección — una URL temporal que captura y muestra cada solicitud recibida, con headers y body formateados (SafeHook hace exactamente eso, y hay otras opciones que comparamos más adelante). Dispara un evento de prueba y examina lo que llega antes de escribir una sola línea de código.

Cuando pases a desarrollar el endpoint de verdad en tu máquina, te vas a topar con el clásico "el proveedor no alcanza mi localhost" — los caminos para resolverlo (túneles, reenvío y CLIs) están en Cómo probar webhooks en localhost. Y antes de ir a producción, vale la pena repasar los 10 errores más comunes al implementar webhooks — casi todos son evitables con decisiones simples tomadas a tiempo.

Resumen

Un webhook es el proveedor llamándote vía HTTP cuando ocurre un evento — el timbre, no la vigilia en la puerta.
El contrato básico: POST con JSON, respuesta 2xx rápida, reintentos con backoff en caso de falla.
Producción exige firma validada, idempotencia, cola de procesamiento y monitoreo.
El webhook notifica; la API confirma. Usa ambos.