¿Qué es un webhook? Diferencia con la API y usos

01¿Qué es un webhook y cómo funciona?

Un webhook es un mecanismo sencillo que permite que dos programas se avisen mutuamente mediante eventos. Cuando ocurre algo dentro de un sistema (por ejemplo, cuando se aprueba un pago), este envía una petición HTTP, normalmente una petición POST, a una URL que usted ha definido. En el cuerpo de la petición figuran los detalles del evento, por lo general en formato JSON.

A esta estructura a veces se la llama también API inversa o disparador de eventos, porque quien inicia la comunicación no es el que pide los datos, sino el sistema que los genera. Usted solo dice una vez «cuando ocurra este evento, avíseme en esta dirección»; el resto funciona de forma automática.

Para entender cómo funciona un webhook le resultará más fácil conocer antes la respuesta a la pregunta qué es una API. El webhook forma parte del mundo de las API, pero la dirección se invierte.

1. Se produce el evento: un pedido nuevo, una solicitud de devolución, un stock agotado, un pago aprobado.
2. El sistema de origen envía una petición POST a la dirección de webhook registrada.
3. El sistema receptor valida la petición, procesa los datos y devuelve una respuesta del tipo 200.
4. Si no llega respuesta, el sistema de origen suele reintentar la petición a intervalos determinados.

02Diferencia entre webhook y API

En el uso clásico de una API, el cliente pregunta al servidor a intervalos regulares «¿hay algo nuevo?». Este método se llama polling (sondeo). Si no hay datos nuevos, cada petición se desperdicia; y si los hay, hay que esperar a la siguiente consulta.

Aquí es donde aparece la diferencia entre webhook y API: en el webhook no hay quien pregunte, hay quien avisa. La notificación llega en el momento del evento y no se genera tráfico innecesario. Sin embargo, el webhook no lo sustituye todo; para listar datos históricos, filtrar o actualizar registros sigue haciendo falta la API.

03Usos de los webhooks

El uso de webhooks aparece en casi cualquier trabajo digital. Los proveedores de pago, las empresas de transporte, los marketplaces, los servicios de correo electrónico, los repositorios de código y las herramientas de comunicación suelen enviar sus notificaciones de eventos mediante webhooks.

E-commerce y pagos

Cuando un cliente completa su pago, la plataforma de pagos envía a su tienda la notificación de «pago correcto» y el pedido se confirma automáticamente. En los pagos con redirección, como 3D Secure, esto permite que el pedido no se pierda aunque se cierre el navegador. El flujo de pedidos es el centro del planteamiento de la integración de e-commerce.

Envíos y marketplaces

Cuando el paquete sale o se entrega, el sistema de la empresa de transporte puede notificar el estado y al cliente le llega un SMS o un correo automático. Del mismo modo, en los proyectos de integración de envíos y de integración con marketplaces, eventos como un pedido nuevo, una cancelación o una devolución se procesan al instante.

Desarrollo de software y herramientas de equipo

Iniciar las pruebas y el proceso de publicación cuando se envía un nuevo commit al repositorio, enviar un aviso al canal de mensajería del equipo cuando se rellena un formulario o actualizar el calendario cuando llega una reserva son escenarios típicos de webhook.

04Ejemplo de petición webhook

Una petición webhook suele llevar el tipo de evento, su momento y los datos del registro correspondiente. El ejemplo siguiente es un cuerpo típico que podría enviarse al crearse un pedido. Los nombres de los campos varían en cada servicio; tome como referencia la documentación del propio servicio.

Por el lado receptor basta un pequeño punto de acceso que atienda esta petición. A continuación verá un ejemplo sencillo escrito con Node.js y Express. En un proyecto real hay que añadir siempre la verificación de firma y una estructura de colas.

{
  "event": "order.created",
  "created_at": "2026-01-15T10:24:00Z",
  "data": {
    "order_id": "10458",
    "total": 1249.90,
    "currency": "TRY",
    "status": "paid"
  }
}

const express = require('express');
const app = express();

app.post('/webhooks/siparis', express.json(), (req, res) => {
  const olay = req.body;
  // 1) Verificar la firma  2) Añadir a la cola  3) Responder de inmediato
  console.log('Gelen olay:', olay.event);
  res.sendStatus(200);
});

app.listen(3000);

05¿Cómo se garantiza la seguridad de un webhook?

La dirección del webhook es un punto de acceso abierto a internet. Cualquiera que conozca la dirección puede enviar allí una petición falsa. Por eso no hay que fiarse de ninguna petición que llegue sin verificación de firma.

La mayoría de los servicios serios firman la petición con una clave secreta compartida y envían la firma en una cabecera HTTP. El sistema receptor hace el mismo cálculo y compara las firmas; la petición que no coincide se rechaza.

• Utilice únicamente direcciones HTTPS; no envíe datos con HTTP simple.
• Aplique siempre métodos de verificación como la firma HMAC.
• Compruebe la marca de tiempo de la petición para impedir que se reproduzcan peticiones antiguas.
• No escriba la clave secreta en el repositorio de código; guárdela en una variable de entorno.
• Antes de escribir los datos recibidos directamente en la base de datos, compruebe su esquema.

06Errores frecuentes y soluciones

Configurar un webhook es fácil, pero hacerlo funcionar con solidez requiere cuidado. Los problemas más habituales en los proyectos son las peticiones repetidas y las respuestas lentas.

Procesar dos veces el mismo evento

Cuando el sistema de origen no recibe respuesta, vuelve a enviar la petición; por eso el mismo pedido puede llegar dos veces. La solución es diseñar una operación idempotente: registre el identificador único de cada evento y, si llega un identificador ya procesado, limítese a devolver una respuesta correcta y seguir.

Tiempo de espera agotado

Si el punto de acceso intenta hacer a la vez tareas largas, como emitir una factura o enviar un correo, al recibir la petición, la respuesta se retrasa y el sistema de origen cuenta un error. El método correcto es recibir la petición, añadirla a una cola de trabajos y responder de inmediato; las tareas pesadas se ejecutan en segundo plano.

Desorden en la secuencia

Los eventos no siempre llegan en el orden en que se produjeron; la notificación de «enviado» puede llegar antes que la de «pagado». Guarde en sus registros el momento del evento y evalúe las transiciones de estado según ese momento.

07¿Webhook o herramienta de automatización lista para usar?

En escenarios sencillos, pueden servir herramientas de automatización que escuchan webhooks sin escribir código. Analizamos con detalle sus puntos fuertes y débiles en nuestro artículo qué es el low-code. Pero en los flujos que son el corazón del negocio, como pedidos, pagos y stock, es importante tener el control.

Si sus reglas de negocio son específicas, si hay varios sistemas conectados entre sí o si el volumen de datos crece, es más fiable montar la arquitectura de webhooks dentro de su propio software. En este terreno, el enfoque de desarrollo de software a medida reduce la dependencia de capas intermedias.

El planteamiento de las soluciones de software y de las soluciones integradas de Aurora también se basa en este principio: los sistemas hablan directamente entre sí y se eliminan las capas innecesarias.

08Lista de control antes de configurar un webhook

Responder a las preguntas siguientes antes de montar una infraestructura de notificaciones automáticas evita de entrada la mayoría de los problemas posteriores.

1. ¿Qué eventos son realmente necesarios? Suscribirse a todos genera una carga innecesaria.
2. ¿El punto de acceso es accesible por HTTPS y verifica la firma?
3. ¿Se guarda un registro del identificador único para los eventos que llegan repetidos?
4. ¿Se registran y se pueden supervisar las peticiones fallidas?
5. Si no llega un webhook, ¿existe una comprobación de respaldo que recupere los datos con la API?
6. En pasos críticos como la contabilidad y la facturación, ¿se controla el riesgo de doble registro con la integración contable?