Webhook

Definición

Un webhook es un mecanismo de comunicación entre sistemas en el que un servidor envía automáticamente una petición HTTP a otro cuando ocurre un evento determinado. A diferencia de una API tradicional, donde el cliente pregunta repetidamente "¿hay algo nuevo?", con un webhook es el servidor el que dice "ha pasado esto, te aviso".

La analogía más clara: una API normal es como llamar tú al teléfono del banco cada hora para preguntar si te ha entrado la nómina. Un webhook es que el banco te mande un SMS solo cuando entra. Cero esfuerzo, en tiempo real, sin esperas.

En arquitectura web se les llama también HTTP callbacks o reverse APIs, porque invierten el flujo habitual: el servidor del proveedor (Stripe, GitHub, Holded) se convierte en cliente y manda la petición al endpoint del consumidor.

Cómo funciona

El ciclo de vida de un webhook tiene tres fases:

1. Registro: el consumidor le dice al proveedor "cuando ocurra X, mándame una petición a esta URL". Esa URL es el endpoint del webhook, normalmente protegido por una clave secreta o firma HMAC.
2. Disparo del evento: en el proveedor ocurre algo relevante (un pago se completa, un PR se mergea, un cliente se da de alta). El proveedor genera un payload JSON con los detalles.
3. Entrega HTTP: el proveedor hace un POST a la URL registrada con el payload en el cuerpo. El consumidor responde rápido con un 200 OK para confirmar la recepción y procesa el evento en segundo plano.

Los proveedores serios reintentan la entrega varias veces si reciben un error 5xx o timeout, con backoff exponencial. Stripe, por ejemplo, reintenta hasta 3 días.

Ejemplo práctico

En IMDICA queremos saber al instante cuando un cliente paga una factura por Stripe para activar automáticamente la preparación del pedido en almacén. En lugar de consultar la API de Stripe cada 5 minutos, registramos un webhook:

• URL del endpoint: https://imdica.es/api/stripe/webhook
• Evento suscrito: payment_intent.succeeded

Cuando un cliente paga, Stripe nos hace en menos de un segundo:

POST /api/stripe/webhook HTTP/1.1
Stripe-Signature: t=1716480000,v1=abc123...
Content-Type: application/json

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_xxx",
      "amount": 24500,
      "metadata": { "pedido_id": "P-2026-4821" }
    }
  }
}

Nuestro servidor valida la firma, marca el pedido como pagado en el ERP y dispara la orden de preparación. Total: dos segundos desde el clic del cliente hasta que el operario ve el pedido en la tablet del almacén.

Webhook vs API tradicional

Para datos que cambian con poca frecuencia (un evento al día), el webhook ahorra miles de peticiones inútiles. Para datos que necesitas bajo demanda, la API tradicional sigue siendo más práctica.

Errores comunes

• No validar la firma: cualquiera que descubra tu URL puede mandarte payloads falsos. Siempre verifica el header de firma (Stripe-Signature, X-Hub-Signature-256, etc.).
• Tardar en responder: si tu endpoint tarda más de unos segundos, el proveedor reintentará y duplicará eventos. Responde 200 inmediato y procesa en cola asíncrona.
• No ser idempotente: el mismo evento puede llegarte dos veces (reintento, doble entrega). Identifica cada webhook por su ID único y guarda los procesados.
• Endpoint sin HTTPS: muchos proveedores se niegan a entregar a URLs HTTP planas. Usa siempre TLS.

Cuándo usarlo

Sí, usa webhooks cuando:

• Necesitas reaccionar en tiempo real a eventos de un sistema externo.
• El evento es relativamente infrecuente (no miles por segundo).
• Tu servidor puede exponer un endpoint público y persistente.

No, evítalos cuando:

• Estás detrás de un firewall sin URL pública (usa polling o cola tipo SQS).
• El volumen es masivo y constante (mejor un stream tipo Kafka o EventBridge).
• Solo necesitas datos cuando el usuario interactúa (la API directa basta).

Referencias

• Stripe Webhooks Documentation — referencia canónica con buenas prácticas
• GitHub Webhooks — explicación práctica con ejemplos de eventos
• MDN · HTTP — base del protocolo sobre el que se construyen