Qué es un webhook y cuándo utilizarlo

Un webhook es una forma de avisar a otro sistema que ocurrió un evento. En vez de consultar una API cada pocos segundos para preguntar si hay novedades, la aplicación receptora publica una URL y el emisor realiza una solicitud HTTP cuando tiene algo que comunicar. El mensaje puede representar una compra creada, un documento aprobado o cualquier otro cambio definido por el contrato de integración.

La idea es sencilla, pero una implementación útil requiere más que exponer una ruta. Hay que decidir qué eventos existen, cómo reconocerlos, qué respuesta espera el emisor, cómo autenticar el mensaje y qué sucede si la entrega falla o se repite. Cada proveedor define su propio contrato: nombres de encabezados, estructura del cuerpo, método de autenticación, plazos y política de reintentos. Su documentación oficial siempre prevalece sobre un ejemplo genérico.

Webhook y API no son alternativas idénticas

Una API tradicional permite solicitar o modificar información cuando el cliente lo decide. Un webhook invierte la iniciativa: el emisor llama al receptor al producirse un evento. Ambos mecanismos suelen complementarse.

Imagina una plataforma hipotética de documentos. Su API permite consultar el estado completo de un documento. Su webhook document.approved avisa que el estado cambió. El receptor puede actuar con el contenido recibido o consultar después la API para obtener la versión actual. Así, el webhook funciona como señal o disparador, no necesariamente como copia definitiva de todos los datos.

Esta diferencia ayuda a elegir:

• usa una API cuando necesitas información bajo demanda;
• usa un webhook cuando necesitas reaccionar a cambios sin sondeo frecuente;
• combina ambos cuando el aviso debe verificarse o enriquecerse con una consulta posterior;
• considera procesamiento por lotes cuando la inmediatez no aporta valor.

Un webhook tampoco es una conexión permanente. Normalmente es una solicitud HTTP independiente. Si necesitas comunicación bidireccional continua y de baja latencia, tecnologías como WebSocket pueden encajar mejor. MDN explica las diferencias básicas de la API WebSocket y su modelo de conexión persistente.

Cuándo suele ser una buena elección

Los webhooks son apropiados cuando el evento ocurre de forma irregular y el receptor necesita enterarse pronto. Por ejemplo, una herramienta de soporte puede avisar que se creó un ticket; un sistema editorial, que una publicación fue aprobada; y una plataforma logística, que cambió el estado de un envío.

También ayudan cuando muchas aplicaciones consumidoras reaccionan al mismo tipo de cambio. Cada una mantiene su propia lógica sin obligar al emisor a conocer qué hará después con el aviso.

No siempre son la mejor opción. Si el receptor no puede publicar una URL accesible, si los cambios se agrupan una vez al día o si el proceso exige una respuesta síncrona inmediata para continuar, otro mecanismo puede resultar más simple. Elegir webhooks por moda añade operación: certificados TLS, observabilidad, reintentos, autenticación y manejo de duplicados.

Antes de decidir, responde estas preguntas:

1. ¿Qué evento necesita conocer el receptor?
2. ¿Qué demora es aceptable?
3. ¿Puede el receptor estar temporalmente fuera de servicio?
4. ¿Qué información mínima debe contener el mensaje?
5. ¿Existe una API para recuperar el estado si se pierde contexto?
6. ¿Cómo se resolverán mensajes repetidos o fuera de orden?

Anatomía de una entrega

Un flujo hipotético puede seguir estos pasos:

1. el consumidor registra una URL HTTPS;
2. el emisor guarda esa suscripción y los eventos elegidos;
3. ocurre un evento y el emisor crea una identidad estable para él;
4. el emisor envía una solicitud, normalmente POST;
5. el receptor autentica el mensaje según el contrato;
6. el receptor registra el evento o lo coloca en una cola;
7. responde con el código HTTP acordado;
8. procesa la acción de negocio de forma idempotente.

El RFC 9110 define la semántica general de HTTP, pero no establece un formato universal para webhooks. Un 200, un 202 o cualquier otro código solo tiene el significado operativo que el contrato haya documentado dentro de la semántica HTTP aplicable.

Conviene responder rápido y mover el trabajo costoso fuera de la solicitud. Si generar un informe tarda treinta segundos, el endpoint puede validar y almacenar el evento, responder, y dejar el informe a un trabajador asíncrono. Esto reduce expiraciones de tiempo, aunque exige una cola o registro duradero y una estrategia para fallos internos.

Un receptor mínimo en JavaScript

Este ejemplo autocontenido usa el servidor HTTP de Node.js. Ilustra límites de tamaño, análisis de JSON y respuesta rápida; no incluye autenticación porque esa parte depende del contrato concreto. No debe desplegarse como plantilla completa sin añadir los controles exigidos por el proveedor.

import { createServer } from "node:http";

const maximumBodyBytes = 256_000;

createServer((request, response) => {
  if (request.method !== "POST" || request.url !== "/webhooks/events") {
    response.writeHead(404).end();
    return;
  }

  const chunks = [];
  let receivedBytes = 0;
  let bodyRejected = false;

  request.on("data", (chunk) => {
    if (bodyRejected) return;
    receivedBytes += chunk.length;
    if (receivedBytes > maximumBodyBytes) {
      bodyRejected = true;
      chunks.length = 0;
      response.writeHead(413).end();
      return;
    }
    chunks.push(chunk);
  });

  request.on("end", () => {
    if (bodyRejected) return;
    try {
      const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));

      if (typeof event.id !== "string" || typeof event.type !== "string") {
        response.writeHead(400).end();
        return;
      }

      console.log("Evento aceptado para procesamiento", event.id, event.type);
      response.writeHead(202).end();
    } catch {
      response.writeHead(400).end();
    }
  });

  request.on("error", () => {
    if (!response.headersSent) response.writeHead(400).end();
  });
}).listen(Number(process.env.PORT ?? "8080"));

En un servicio real, console.log no sustituye un almacenamiento duradero. También faltan control de acceso, validación completa del esquema, protección frente a abuso y una cola. La documentación de Node.js describe el módulo HTTP y su modelo de solicitudes, incluidos eventos y límites que deben entenderse antes de operar un servidor expuesto.

Qué debe definir el contrato

Un contrato claro evita suposiciones entre equipos. Como mínimo, documenta:

• URL, método y tipo de contenido;
• catálogo y versión de eventos;
• identificador estable del evento;
• esquema de cada carga útil;
• mecanismo de autenticación y rotación de credenciales;
• códigos que confirman recepción;
• límites de tiempo y tamaño;
• política de reintentos y periodo de entrega;
• comportamiento ante eventos duplicados o desordenados;
• forma de probar y reproducir entregas.

Versionar no significa incluir siempre /v2 en la URL. Puede usarse una versión de esquema o un nuevo tipo de evento. Lo importante es que un cambio incompatible no sorprenda a receptores existentes.

Operación y seguridad práctica

Publicar una URL crea una superficie de entrada. Usa HTTPS, limita el tamaño del cuerpo, valida el tipo de contenido y procesa solo eventos conocidos. Autentica antes de ejecutar acciones. Nunca coloques secretos en el código fuente ni en URLs; usa variables de entorno o un gestor de secretos apropiado. Evita registrar cargas completas si contienen datos personales.

La autenticación no elimina todos los riesgos. Un mensaje válido puede repetirse, llegar tarde o contener un dato legítimo que ya no representa el estado actual. Por eso la firma, los reintentos con espera progresiva y la idempotencia del receptor resuelven problemas distintos.

Observa al menos cantidad de entregas, latencia, códigos de respuesta, reintentos y antigüedad del evento más viejo sin procesar. Las alertas deben conducir a una acción: revisar credenciales, ampliar capacidad, corregir un despliegue o reproducir una entrega desde una fuente autorizada.

Una decisión basada en el flujo

Un webhook es valioso cuando convierte un cambio remoto en una reacción local oportuna sin sondeo constante. No garantiza entrega única, orden perfecto ni seguridad absoluta. Esas propiedades dependen del diseño completo y del contrato de cada proveedor.

Empieza por el evento y la necesidad operativa, no por el endpoint. Define una identidad estable, una respuesta rápida, recuperación ante fallos y límites de datos. Luego aplica exactamente la autenticación indicada por el proveedor; si el contrato propone firmas, revisa la guía sobre verificación de HMAC-SHA256 como introducción general, sin reemplazar esa documentación oficial.