Webhook

Webhook es un mecanismo de comunicación entre aplicaciones mediante el cual un sistema envía automáticamente una solicitud, generalmente HTTP o HTTPS, hacia una dirección previamente registrada cuando ocurre un evento determinado. Permite que una aplicación reciba notificaciones sobre pagos, formularios, pedidos, mensajes, cambios de estado, publicaciones, registros, entregas y otras acciones sin consultar constantemente al sistema de origen.

Un webhook suele estar formado por un productor de eventos, un evento, una URL receptora o endpoint, un conjunto de encabezados y una carga útil o payload. Cuando ocurre el evento, el productor realiza una solicitud hacia el endpoint y entrega información que permite al receptor actualizar datos, ejecutar una automatización, iniciar un proceso o comunicar el cambio a otro sistema.

En marketing digital, los webhooks se utilizan para conectar formularios, CRM, plataformas publicitarias, tiendas en línea, servicios de pago, sistemas de mensajería, herramientas de email marketing, gestores de contenidos, agentes de inteligencia artificial y plataformas de automatización como n8n, Zapier y Make. Su utilidad principal consiste en transmitir cambios de manera inmediata o casi inmediata y reducir la necesidad de realizar consultas periódicas mediante una API.

Introducción

Las aplicaciones digitales rara vez funcionan de manera aislada. Una tienda necesita comunicarse con su procesador de pagos, el sistema de pagos con el inventario, el inventario con el proveedor logístico y el sistema comercial con un CRM.

Una integración puede consultar continuamente una API para comprobar si ocurrió un cambio. Por ejemplo, un sistema podría preguntar cada minuto si existe un pago nuevo. Este método se conoce como polling o sondeo periódico.

El polling puede funcionar en escenarios sencillos, aunque produce solicitudes incluso cuando no existen novedades. También puede introducir retrasos, consumir límites de API y aumentar costos de infraestructura.

Los webhooks invierten el flujo. El sistema de origen informa al receptor cuando sucede el evento. En lugar de preguntar repetidamente «¿hay algo nuevo?», la aplicación espera una notificación.

Un flujo habitual puede describirse de la siguiente manera:

Una aplicación registra una URL receptora.

El sistema de origen almacena esa suscripción.

Ocurre un evento relevante.

El sistema genera una representación del evento.

Se crea una solicitud HTTP.

La solicitud se envía hacia la URL registrada.

El receptor verifica la autenticidad.

El receptor registra o procesa el evento.

El receptor devuelve una respuesta HTTP.

El productor considera la entrega exitosa o programa un reintento.

Por ejemplo, una plataforma de pagos puede enviar un evento cuando una transacción se confirma. El sistema receptor puede marcar un pedido como pagado, reducir inventario, enviar un comprobante y comenzar el proceso de entrega.

Los webhooks permiten construir integraciones reactivas. Una aplicación responde a acontecimientos en vez de ejecutar comprobaciones continuas.

La expresión también se utiliza para describir:

la URL receptora;
la suscripción configurada;
la solicitud enviada;
el sistema completo de entrega de eventos;
el código que procesa la notificación.

El contexto determina si webhook se refiere al mecanismo general, al endpoint o a una entrega individual.

Los webhooks suelen transportar datos mediante JSON, aunque también pueden utilizar:

formularios codificados;
XML;
texto;
contenido binario;
formatos específicos del proveedor.

La mayoría utiliza solicitudes `POST`, aunque una implementación podría emplear otros métodos si su contrato lo establece.

No existe un único protocolo universal de webhook que determine nombres de encabezados, firmas, reintentos, formato de eventos y respuestas para todos los proveedores. Cada plataforma documenta su propio contrato, aunque existen especificaciones como CloudEvents y OpenAPI que facilitan describir y normalizar determinados aspectos.

Definición

Webhook puede definirse como una notificación programática iniciada por un sistema y enviada hacia un endpoint remoto como consecuencia de un evento.

Una definición operativa puede apoyarse en los siguientes criterios:

Orientación a eventos: la entrega se origina cuando ocurre un cambio o acontecimiento.

Comunicación saliente: el sistema productor inicia la solicitud.

Endpoint registrado: el receptor proporciona una URL o destino.

Entrega automática: no necesita una solicitud manual por cada evento.

Payload estructurado: la notificación incluye información sobre lo ocurrido.

Contrato documentado: productor y consumidor acuerdan formato, encabezados y semántica.

Procesamiento asíncrono: el evento puede llegar fuera del flujo donde se originó.

Respuesta de confirmación: el receptor devuelve un código que indica el resultado de la entrega.

Posibilidad de reintento: el productor puede volver a enviar eventos fallidos.

Seguridad verificable: el receptor debe comprobar autenticidad e integridad.

Tolerancia a duplicados: una misma notificación puede recibirse más de una vez.

Independencia de interfaz humana: el intercambio ocurre entre sistemas.

Los webhooks se describen frecuentemente como API inversas o reverse APIs. La expresión destaca que el proveedor envía información hacia el consumidor en vez de esperar que el consumidor la solicite.

La comparación resulta útil, aunque un webhook continúa utilizando una interfaz y un contrato. El receptor publica un endpoint y el productor actúa como cliente HTTP durante la entrega.

Terminología

Webhook. Mecanismo mediante el cual un sistema envía una notificación a otro cuando ocurre un evento.

Endpoint de webhook. URL o servicio que recibe las entregas.

URL de callback. Dirección proporcionada para recibir una llamada posterior.

Callback HTTP. Solicitud HTTP ejecutada como respuesta a un evento.

Productor. Sistema que detecta el evento y envía la notificación.

Emisor. Aplicación responsable de realizar la solicitud.

Consumidor. Sistema que recibe y procesa el evento.

Receptor. Endpoint o aplicación que acepta la entrega.

Evento. Representación de un acontecimiento ocurrido dentro del productor.

Tipo de evento. Nombre que clasifica el acontecimiento, como `payment.succeeded` o `lead.created`.

Acción. Variante específica dentro de un tipo de evento, como creado, actualizado o eliminado.

Payload. Contenido enviado dentro de la solicitud.

Entrega. Intento individual de enviar un evento hacia un endpoint.

Delivery ID. Identificador único de una entrega.

Event ID. Identificador único del evento lógico.

Suscripción. Configuración que relaciona eventos con un destino.

Webhook secret. Secreto compartido utilizado para calcular o verificar firmas.

Firma. Código criptográfico que permite verificar origen e integridad.

Reintento. Nuevo intento de entregar un evento que no fue confirmado.

Redelivery. Reenvío manual o automático de una entrega.

Dead-letter queue. Almacenamiento donde se conservan eventos que no pudieron procesarse después de varios intentos.

Idempotencia. Propiedad que permite procesar varias veces la misma operación sin duplicar sus efectos.

Acknowledgement. Respuesta utilizada para confirmar recepción.

Timeout. Tiempo máximo que el productor espera la respuesta del receptor.

Polling. Consultas periódicas destinadas a detectar cambios.

Long polling. Solicitud que permanece abierta durante un periodo esperando novedades.

Streaming de eventos. Entrega continua mediante una conexión o infraestructura de mensajería.

Event bus. Sistema que distribuye eventos entre productores y consumidores.

Contexto histórico y evolución

Los webhooks surgieron de la convergencia entre arquitecturas orientadas a eventos, sistemas de callbacks, HTTP y aplicaciones web conectadas.

Callbacks en programación

Un callback es una función o referencia que se proporciona a otra parte del programa para que sea ejecutada cuando ocurre una condición.

Los callbacks se utilizan en:

eventos de interfaz;
operaciones asíncronas;
sistemas operativos;
redes;
procesamiento de archivos;
bibliotecas.

Los webhooks trasladan esta idea hacia sistemas distribuidos. En vez de proporcionar una función dentro del mismo proceso, el consumidor proporciona una URL que será llamada mediante HTTP.

Arquitecturas orientadas a eventos

Los sistemas orientados a eventos representan cambios mediante mensajes o señales.

Un productor puede publicar un evento sin conocer todos los procesos que reaccionarán posteriormente.

Este modelo se utilizó durante décadas en:

sistemas empresariales;
colas de mensajes;
interfaces gráficas;
telecomunicaciones;
automatización industrial;
bases de datos.

Los webhooks aplicaron el mismo principio a integraciones accesibles mediante la Web.

CGI y formularios web

Las primeras aplicaciones web permitían enviar datos desde formularios hacia programas ejecutados en servidores.

El servidor recibía una solicitud, procesaba la información y producía una respuesta.

Esta infraestructura proporcionó la base técnica para endpoints capaces de recibir notificaciones de otras aplicaciones.

API y servicios web

El crecimiento de servicios web permitió que empresas externas consultaran y modificaran datos mediante interfaces documentadas.

Las primeras integraciones dependían frecuentemente de polling. Un consumidor consultaba el proveedor en intervalos para comprobar cambios.

El aumento del número de integraciones mostró las limitaciones de este método:

solicitudes innecesarias;
consumo de cuotas;
latencia;
complejidad de sincronización;
carga sobre servidores.

Popularización del término

El término webhook comenzó a utilizarse ampliamente durante la segunda mitad de la década de 2000 para describir callbacks realizados mediante HTTP.

Jeff Lindsay fue una de las personas asociadas con la divulgación del concepto y con iniciativas orientadas a extender la Web mediante notificaciones programáticas.

La expresión adquirió popularidad dentro de plataformas de desarrollo, pagos, comercio electrónico y automatización.

Plataformas de desarrollo

Servicios como GitHub adoptaron webhooks para informar acontecimientos relacionados con repositorios:

push;
pull request;
issue;
release;
comentario;
instalación de una aplicación.

Los webhooks permitieron activar compilaciones, pruebas, despliegues, notificaciones y sincronizaciones.

Plataformas de pagos

Los pagos digitales aumentaron la necesidad de procesar cambios asíncronos.

Una operación puede permanecer pendiente y confirmarse después de que el usuario abandona la página. Los webhooks permiten que el sistema comercial conozca el resultado final.

Stripe, PayPal y otros proveedores utilizan webhooks para informar:

pagos confirmados;
pagos fallidos;
disputas;
reembolsos;
suscripciones;
facturas;
transferencias.

Automatización sin código

Zapier, IFTTT, Make y posteriormente n8n popularizaron la idea de conectar aplicaciones mediante disparadores y acciones.

Un webhook puede funcionar como:

disparador de un flujo;
acción que envía información;
puente entre una aplicación sin integración directa y otra plataforma.

Comercio electrónico

Shopify, WooCommerce y otras plataformas utilizan webhooks para informar cambios en:

pedidos;
clientes;
productos;
inventarios;
entregas;
devoluciones.

CloudEvents

CloudEvents se desarrolló dentro de la Cloud Native Computing Foundation para describir eventos de una manera común entre servicios y plataformas.

La especificación define atributos como:

identificador;
fuente;
tipo;
versión;
hora;
sujeto;
contenido.

CloudEvents no obliga a utilizar exclusivamente webhooks. Puede transportarse mediante HTTP, sistemas de mensajería y otros protocolos.

Su importancia consiste en proporcionar una envoltura interoperable para representar eventos.

OpenAPI

OpenAPI 3.1 incorporó una sección `webhooks` para describir solicitudes que una API puede iniciar hacia destinos proporcionados por consumidores.

Esta capacidad permite documentar:

rutas;
métodos;
encabezados;
cuerpos;
esquemas;
respuestas.

Event destinations

Las plataformas recientes comienzan a ofrecer destinos alternativos además de endpoints HTTP.

Un evento puede enviarse hacia:

Amazon EventBridge;
Azure Event Grid;
Google Cloud Pub/Sub;
colas;
buses empresariales;
almacenamiento;
plataformas de observabilidad.

El webhook continúa siendo una opción accesible y ampliamente compatible, mientras las arquitecturas de gran escala pueden utilizar infraestructuras especializadas.

Fundamentos teóricos

Arquitectura orientada a eventos. El sistema reacciona a hechos significativos.

Patrón publish-subscribe. Los consumidores se suscriben a eventos producidos por otro sistema.

Inversión de control. El consumidor no decide cuándo ejecutar la consulta; el productor inicia la comunicación.

Comunicación asíncrona. El acontecimiento y su procesamiento pueden ocurrir en momentos diferentes.

Entrega push. La información es enviada por el productor hacia el consumidor.

Acoplamiento mediante contrato. Los sistemas dependen del significado y estructura de los eventos.

Consistencia eventual. Los sistemas pueden presentar estados distintos durante un periodo y sincronizarse después.

Entrega al menos una vez. El productor intenta asegurar que el evento llegue, aunque puede generar duplicados.

Entrega como máximo una vez. El sistema no reintenta o evita duplicados, con riesgo de perder eventos.

Entrega exactamente una vez. Objetivo difícil de garantizar de extremo a extremo en sistemas distribuidos.

Idempotencia. El receptor evita que los duplicados produzcan efectos adicionales.

Durabilidad. El productor conserva eventos o entregas durante un periodo para permitir reintentos.

Orden parcial. Algunos eventos conservan orden dentro de un recurso, mientras otros pueden llegar fuera de secuencia.

Autenticación del origen. El receptor verifica quién produjo la solicitud.

Integridad del mensaje. La firma demuestra que el contenido no fue modificado.

Protección frente a replay. El receptor detecta solicitudes válidas reenviadas maliciosamente.

Backpressure. El sistema debe administrar situaciones donde los eventos llegan más rápido de lo que pueden procesarse.

Separación entre recepción y procesamiento. El endpoint confirma rápidamente y delega el trabajo a una cola o worker.

Observabilidad distribuida. Los identificadores permiten seguir el evento entre sistemas.

Funcionamiento

Un webhook comienza con la configuración de una suscripción.

El consumidor proporciona normalmente:

URL;
tipos de eventos;
secreto;
versión;
filtros;
configuración de formato.

Cuando ocurre el evento, el productor crea un objeto de evento.

Ejemplo:

<syntaxhighlight lang="json"> {

 "id": "evt_01JXYZ",
 "type": "order.paid",
 "created_at": "2026-07-14T18:30:00Z",
 "data": {
   "order_id": "ORD-25001",
   "customer_id": "CUS-501",
   "amount": 189900,
   "currency": "MXN"
 }

} </syntaxhighlight>

Posteriormente, el productor puede crear una solicitud:

<syntaxhighlight lang="http"> POST /webhooks/pagos HTTP/1.1 Host: integraciones.ejemplo.com Content-Type: application/json User-Agent: Proveedor-Webhook/1.0 X-Webhook-Id: evt_01JXYZ X-Webhook-Timestamp: 1784053800 X-Webhook-Signature: sha256=abcdef123456...

{ "id": "evt_01JXYZ", "type": "order.paid", "created_at": "2026-07-14T18:30:00Z", "data": { "order_id": "ORD-25001", "amount": 189900, "currency": "MXN" } } </syntaxhighlight>

El receptor debe:

leer el cuerpo original;

obtener los encabezados;

comprobar el timestamp;

calcular la firma;

comparar la firma de forma segura;

validar la estructura;

comprobar el tipo de evento;

registrar el identificador;

evitar procesamiento duplicado;

almacenar o encolar el evento;

devolver una respuesta rápida.

Una respuesta exitosa puede ser:

<syntaxhighlight lang="http"> HTTP/1.1 200 OK Content-Type: application/json

{ "received": true } </syntaxhighlight>

Algunos proveedores aceptan cualquier código `2xx`. Otros requieren códigos específicos.

Si el endpoint devuelve un error, agota el tiempo o no puede conectarse, el productor puede programar un nuevo intento.

Metodología

El diseño e implementación de una integración mediante webhooks puede seguir una metodología estructurada.

1. Definir el objetivo. Se identifica qué proceso debe activarse y qué valor aporta recibir el evento.

2. Revisar la documentación del proveedor. Se analizan tipos de eventos, payloads, firmas, reintentos y límites.

3. Seleccionar los eventos mínimos. Se evita suscribirse a notificaciones innecesarias.

4. Diseñar el endpoint. Se define URL, método, autenticación y capacidad esperada.

5. Configurar HTTPS. El endpoint debe utilizar una conexión protegida.

6. Crear un secreto. Se genera un valor aleatorio y se almacena en un gestor seguro.

7. Implementar verificación de firmas. Se utiliza el cuerpo original y el algoritmo documentado.

8. Validar timestamps. Se rechazan solicitudes demasiado antiguas cuando el proveedor incluye tiempo firmado.

9. Validar el payload. Se comprueban tipos, campos, límites y versión.

10. Crear almacenamiento de eventos. Se registran identificador, tipo, hora, estado y cuerpo.

11. Diseñar idempotencia. El sistema evita repetir efectos.

12. Separar recepción y procesamiento. El endpoint encola el evento y responde rápidamente.

13. Implementar workers. Los procesos de fondo ejecutan las acciones comerciales.

14. Diseñar reintentos internos. Los errores temporales se reintentan con límites.

15. Crear dead-letter queue. Los eventos imposibles de procesar se conservan para revisión.

16. Manejar orden. El estado actual se consulta cuando los eventos pueden llegar fuera de secuencia.

17. Gestionar versiones. El contrato debe actualizarse sin romper consumidores.

18. Implementar observabilidad. Se registran entregas, latencias, errores y duplicados.

19. Probar localmente. Se utilizan túneles, CLI o herramientas de simulación.

20. Probar eventos reales de prueba. Se verifica cada tipo y variante.

21. Probar duplicados. El mismo evento se envía varias veces.

22. Probar desorden. Los eventos se procesan en secuencia distinta.

23. Probar fallos. Se simulan timeouts, códigos 500, caídas y payloads inválidos.

24. Desplegar gradualmente. Se activa primero un conjunto limitado de eventos.

25. Monitorear producción. Se establecen alertas sobre entregas fallidas y colas crecientes.

26. Rotar secretos. Se cambia el secreto mediante un periodo de transición.

27. Auditar suscripciones. Se eliminan endpoints y eventos que dejaron de utilizarse.

Elementos principales

Productor de eventos

Es el sistema donde ocurre el acontecimiento.

Puede ser:

plataforma de pagos;
CRM;
tienda;
repositorio;
servicio de correo;
sistema de mensajería;
aplicación interna.

Evento

Representa un hecho ocurrido.

Ejemplos:

`customer.created`;
`lead.updated`;
`payment.succeeded`;
`order.cancelled`;
`message.received`;
`subscription.renewed`.

Un evento debe describir un hecho ocurrido y no una intención ambigua.

Tipo de evento

Permite que el receptor seleccione el manejador apropiado.

Una convención frecuente utiliza:

<syntaxhighlight lang="text"> recurso.acción </syntaxhighlight>

Ejemplos:

<syntaxhighlight lang="text"> customer.created customer.updated customer.deleted </syntaxhighlight>

Las convenciones varían entre proveedores.

Identificador de evento

Permite detectar duplicados y seguir el procesamiento.

Debe ser único dentro del ámbito del productor.

Endpoint

Es la URL que recibe solicitudes.

Ejemplo:

<syntaxhighlight lang="text"> https://api.ejemplo.com/webhooks/stripe </syntaxhighlight>

Conviene separar endpoints por proveedor o nivel de riesgo cuando facilita seguridad, observabilidad y mantenimiento.

Método HTTP

`POST` es el método predominante porque permite enviar un cuerpo y representa una notificación o creación de operación.

El contrato puede utilizar otros métodos en casos específicos.

Encabezados

Los encabezados pueden incluir:

tipo de contenido;
firma;
timestamp;
identificador;
tipo de evento;
versión;
agente de usuario;
información de reintento.

Los nombres dependen del proveedor.

Payload

Contiene los datos del evento.

Puede adoptar dos modelos principales.

Snapshot event. Incluye una representación del recurso en el momento del evento.

Thin event. Incluye identificadores y datos mínimos; el consumidor consulta la API para obtener el recurso actual.

Secreto compartido

Valor conocido por productor y receptor utilizado para verificar firmas.

Debe generarse de manera aleatoria y mantenerse fuera del código fuente.

Firma

Código calculado sobre el cuerpo, timestamp u otros componentes.

HMAC es un mecanismo frecuente para firmas simétricas.

Algunos proveedores utilizan firmas asimétricas mediante claves públicas.

Respuesta HTTP

Indica si la entrega fue aceptada.

Códigos habituales:

`200 OK`;
`202 Accepted`;
`204 No Content`;
`400 Bad Request`;
`401 Unauthorized`;
`403 Forbidden`;
`404 Not Found`;
`409 Conflict`;
`429 Too Many Requests`;
`500 Internal Server Error`;
`503 Service Unavailable`.

La semántica exacta debe consultarse en la documentación del proveedor.

Registro de entregas

El productor puede conservar:

hora;
endpoint;
código;
duración;
intento;
cuerpo;
encabezados;
error.

El consumidor debe mantener su propio registro operativo.

Tipos y variantes

Webhook saliente

Una aplicación envía eventos hacia sistemas externos.

Webhook entrante

Una aplicación proporciona un endpoint para recibir eventos.

Webhook configurable

El usuario registra libremente la URL y selecciona eventos.

Webhook preconfigurado

El destino se encuentra definido dentro de una integración específica.

Webhook por cuenta

Envía eventos relacionados con una cuenta o cliente.

Webhook global

Recibe eventos de múltiples cuentas o recursos.

Webhook de organización

Agrupa acontecimientos de una organización completa.

Webhook de recurso

Se configura para un repositorio, proyecto, tienda o entidad concreta.

Webhook síncrono

El productor necesita una respuesta que influye inmediatamente en la operación.

Estos casos requieren límites estrictos de latencia y disponibilidad.

Webhook asíncrono

La respuesta confirma recepción y el procesamiento ocurre posteriormente.

Es la modalidad más frecuente.

Webhook con payload completo

Incluye los datos necesarios para procesar el evento.

Webhook delgado

Incluye un identificador y obliga a consultar la API.

Webhook firmado con secreto compartido

Utiliza HMAC u otro mecanismo simétrico.

Webhook firmado con clave pública

El productor firma con una clave privada y el consumidor verifica con una clave pública.

Webhook autenticado mediante token

El productor incluye un token en un encabezado o credencial.

Un token estático proporciona menos garantías de integridad que una firma calculada sobre el cuerpo.

Webhook con filtrado

Permite limitar eventos según:

tipo;
cuenta;
producto;
ubicación;
estado;
campo.

Webhook transformado

El productor o intermediario adapta el payload antes de entregarlo.

Webhook fan-out

Un evento se distribuye hacia varios endpoints.

Webhook encadenado

Una entrega inicia otro webhook o automatización.

Las cadenas extensas aumentan latencia y dificultad de diagnóstico.

Webhook bidireccional

Dos sistemas proporcionan endpoints y se envían eventos mutuamente.

Webhook interno

Se utiliza dentro de una organización entre aplicaciones privadas.

Webhook público

Se encuentra expuesto a internet para recibir notificaciones externas.

Webhook de desarrollo

Utiliza un túnel o servicio temporal para pruebas locales.

Webhook manual

El proveedor permite solicitar un reenvío desde un panel o API.

Webhook basado en CloudEvents

Utiliza atributos y estructura definidos por CloudEvents.

Eventos y payloads

Un evento bien diseñado puede incluir:

<syntaxhighlight lang="json"> {

 "specversion": "1.0",
 "id": "evt_789",
 "source": "https://pagos.ejemplo.com/accounts/acct_25",
 "type": "com.ejemplo.payment.succeeded",
 "subject": "payments/pay_501",
 "time": "2026-07-14T18:30:00Z",
 "datacontenttype": "application/json",
 "data": {
   "payment_id": "pay_501",
   "order_id": "ord_100",
   "amount": 189900,
   "currency": "MXN"
 }

} </syntaxhighlight>

Los campos importantes incluyen:

ID. Identifica el evento.

Type. Explica qué ocurrió.

Source. Identifica dónde ocurrió.

Time. Indica cuándo ocurrió.

Subject. Señala el recurso relacionado.

Data. Contiene información propia del evento.

Version. Identifica la versión del contrato.

Account. Señala la cuenta o tenant relacionado.

Previous attributes. Puede indicar qué campos cambiaron.

Attempt. Puede comunicar el número de intento.

El payload debe contener la información suficiente para identificar y procesar el evento sin exponer datos innecesarios.

Snapshot events y thin events

Snapshot event

Incluye una copia del recurso.

Ventajas:

reduce consultas adicionales;
conserva el estado observado;
permite procesamiento aunque la API no esté disponible.

Limitaciones:

payload mayor;
puede contener datos obsoletos;
aumenta exposición de información;
vincula al consumidor con la estructura completa.

Thin event

Incluye principalmente:

identificador;
tipo;
versión;
referencia al recurso.

Ventajas:

payload pequeño;
menor exposición;
el consumidor obtiene la versión actual.

Limitaciones:

necesita otra solicitud;
aumenta latencia;
depende de disponibilidad y permisos de la API;
puede perder el estado histórico exacto.

La selección depende de consistencia, auditoría, privacidad y volumen.

Seguridad

Los endpoints de webhook se encuentran expuestos a solicitudes externas y deben tratar toda entrada como no confiable.

HTTPS

Los endpoints deben utilizar HTTPS.

TLS protege:

confidencialidad en tránsito;
integridad del canal;
autenticación del servidor.

La validación del certificado no debe deshabilitarse en producción.

Firma de webhook

La firma permite verificar que el payload fue producido por una parte que conoce el secreto y que el cuerpo no fue modificado.

Un enfoque frecuente utiliza HMAC-SHA-256.

Conceptualmente:

<syntaxhighlight lang="text"> firma = HMAC_SHA256(secreto, timestamp + "." + cuerpo_original) </syntaxhighlight>

El receptor calcula el valor y lo compara con la firma recibida.

La comparación debe realizarse mediante una función de tiempo constante para reducir ataques de análisis temporal.

Cuerpo original

La firma suele calcularse sobre los bytes exactos de la solicitud.

Si el framework:

analiza JSON;
cambia espacios;
normaliza caracteres;
reordena propiedades;
convierte números;

la verificación puede fallar.

El endpoint debe conservar el cuerpo sin modificar hasta validar la firma.

Timestamp

Firmar un timestamp ayuda a prevenir ataques de repetición.

El receptor puede rechazar solicitudes cuya marca temporal quede fuera de una tolerancia definida.

La tolerancia debe considerar diferencias razonables de reloj y retrasos de red.

Replay attacks

Un atacante puede capturar una solicitud válida y reenviarla.

Las mitigaciones incluyen:

timestamp firmado;
Event ID;
Delivery ID;
registro de solicitudes procesadas;
ventana temporal;
nonce.

Rotación de secretos

Los secretos deben cambiarse periódicamente o después de una exposición.

Durante una transición, el receptor puede aceptar temporalmente la firma calculada con:

secreto anterior;
secreto nuevo.

La ventana debe limitarse y monitorearse.

Tokens en URL

Incluir secretos dentro de la URL puede provocar exposición mediante:

logs;
historial;
proxies;
analítica;
herramientas.

Resulta preferible utilizar encabezados y firmas.

Allowlist de IP

Algunos proveedores publican rangos de IP.

Una allowlist puede funcionar como control adicional, aunque:

los rangos pueden cambiar;
no demuestra integridad;
puede fallar detrás de proxies;
no sustituye la firma.

mTLS

La autenticación mutua mediante certificados puede utilizarse en integraciones de alto privilegio.

Ambas partes verifican certificados durante la conexión.

Validación del tipo de contenido

El receptor debe comprobar el Content-Type esperado.

Validación del esquema

El payload debe validarse contra reglas conocidas:

tipos;
campos requeridos;
longitudes;
enumeraciones;
profundidad.

Autorización del recurso

Una firma válida demuestra origen, pero el receptor también debe comprobar que el evento pertenece a una cuenta o recurso esperado.

Rate limiting

El endpoint debe limitar solicitudes para reducir:

abuso;
fuerza bruta;
denegación;
costos.

Los límites deben permitir picos legítimos.

Tamaño máximo

Deben establecerse límites sobre el cuerpo para evitar consumo excesivo de memoria.

SSRF en productores

Una plataforma que permite registrar URLs arbitrarias puede utilizarse para acceder a:

servicios internos;
metadatos de nube;
redes privadas;
endpoints administrativos.

El productor debe validar destinos, resolver DNS de manera segura y restringir rangos internos cuando corresponda.

Redirecciones

El emisor debe definir si sigue redirecciones.

Seguirlas sin controles puede facilitar SSRF o desviar secretos hacia otro dominio.

Respuestas sensibles

El endpoint no debe devolver:

secretos;
trazas internas;
datos de clientes;
detalles de infraestructura.

Registros

Los logs deben evitar almacenar:

secretos;
firmas completas;
tokens;
datos personales innecesarios;
números financieros completos.

Dependencias

Las bibliotecas utilizadas para firmas, parsing y HTTP deben mantenerse actualizadas.

Fiabilidad y semántica de entrega

La red puede fallar después de que el receptor procese el evento y antes de que el productor reciba la respuesta.

El productor interpreta la ausencia de respuesta como fallo y reenvía el evento.

Por este motivo, numerosos sistemas ofrecen una semántica de entrega al menos una vez.

El receptor debe asumir:

duplicados;
retrasos;
reintentos;
entregas fuera de orden;
eventos faltantes;
caídas parciales.

Idempotencia

La idempotencia evita que un evento repetido produzca efectos duplicados.

Un sistema puede mantener una tabla:

<syntaxhighlight lang="text"> event_id | event_type | status | received_at | processed_at </syntaxhighlight>

Antes de procesar:

intenta registrar el Event ID con una restricción única;

si ya existe, confirma la entrega sin repetir el efecto;

si es nuevo, continúa;

marca el procesamiento como completado.

Ejemplo conceptual:

<syntaxhighlight lang="text"> BEGIN TRANSACTION

INSERT event_id IF duplicate: RETURN success

UPDATE order SET paid = true INSERT payment_record MARK event processed

COMMIT </syntaxhighlight>

La idempotencia debe aplicarse en el nivel del efecto comercial.

Registrar únicamente el Delivery ID puede ser insuficiente cuando un mismo evento se entrega mediante identificadores diferentes.

El proveedor puede generar eventos separados que representan el mismo cambio. En estos casos puede resultar necesario utilizar:

ID del objeto;
tipo de evento;
estado;
identificador de operación comercial.

Orden de eventos

Los webhooks pueden llegar fuera de orden.

Ejemplo:

se crea una suscripción;

se actualiza;

se cancela;

el evento de cancelación llega antes del evento de actualización.

Procesarlos ciegamente en orden de recepción podría restaurar un estado anterior.

Estrategias:

consultar el recurso actual mediante API;
comparar versiones;
comparar timestamps;
utilizar secuencias;
ignorar estados anteriores;
aplicar máquinas de estados;
procesar por clave en una cola ordenada.

Los timestamps no siempre proporcionan un orden total confiable.

Reintentos

El productor puede volver a intentar una entrega cuando ocurre:

timeout;
conexión rechazada;
DNS fallido;
error TLS;
respuesta `5xx`;
respuesta `429`;
códigos no aceptados.

Un esquema puede utilizar exponential backoff:

<syntaxhighlight lang="text"> 1 minuto 5 minutos 30 minutos 2 horas 8 horas 24 horas </syntaxhighlight>

Cada proveedor define:

duración total;
número de intentos;
códigos reintentables;
posibilidad de reenvío manual;
retención de eventos.

El consumidor no debe depender de que todos los proveedores reintenten. GitHub, por ejemplo, distingue entre entregas que pueden necesitar redelivery manual o automatización propia, mientras otros servicios aplican reintentos automáticos.

Recepción rápida y procesamiento asíncrono

Los productores suelen imponer timeouts cortos.

El endpoint debería realizar solamente:

lectura;

verificación;

validación mínima;

deduplicación inicial;

almacenamiento o encolado;

respuesta.

Las tareas lentas deben trasladarse a workers:

envío de correo;
generación de factura;
actualización masiva;
procesamiento de imágenes;
llamadas a terceros;
inteligencia artificial.

Arquitectura recomendada:

<syntaxhighlight lang="text"> Proveedor

↓

Endpoint de webhook

↓

Validación y firma

↓

Base de eventos / cola

↓

Worker

↓

CRM, inventario, correo, analítica </syntaxhighlight>

Este patrón reduce timeouts y permite reintentos internos.

Versionado

Los payloads evolucionan conforme una plataforma añade campos, cambia estructuras o modifica objetos.

Las estrategias incluyen:

versión por endpoint;
versión por cuenta;
encabezado de versión;
campo dentro del evento;
URL versionada;
esquemas compatibles.

Buenas prácticas:

aceptar propiedades desconocidas;
no depender del orden;
diferenciar campos opcionales;
probar nuevas versiones;
mantener fixtures;
desplegar endpoints paralelos;
registrar la versión recibida.

Cambiar el tipo de una propiedad representa una modificación incompatible.

Documentación mediante OpenAPI

OpenAPI permite describir webhooks mediante una estructura semejante a operaciones de API.

Ejemplo simplificado:

<syntaxhighlight lang="yaml"> openapi: 3.1.0 info:

 title: Plataforma de pedidos
 version: 1.0.0

webhooks: orderPaid: post: requestBody: required: true content: application/json: schema: type: object required: - id - type - data properties: id: type: string type: const: order.paid data: type: object responses: "200": description: Evento recibido </syntaxhighlight>

La documentación puede generar:

ejemplos;
validadores;
clientes;
pruebas;
portales técnicos.

CloudEvents

CloudEvents define una manera común de describir eventos.

Atributos principales:

`specversion`;
`id`;
`source`;
`type`;
`subject`;
`time`;
`datacontenttype`;
`dataschema`;
`data`.

Puede representarse mediante:

Modo estructurado. Los atributos se incluyen dentro del cuerpo.

Modo binario. Los atributos se transportan mediante encabezados y el cuerpo contiene los datos.

CloudEvents ayuda cuando una organización integra múltiples productores y desea una envoltura uniforme.

No elimina la necesidad de definir:

seguridad;
reintentos;
suscripciones;
semántica de negocio;
autorización.

Pruebas y desarrollo

Endpoint local

Durante el desarrollo, la aplicación puede ejecutarse en una computadora sin acceso público.

Un túnel HTTPS permite reenviar solicitudes hacia el entorno local.

Herramientas frecuentes:

ngrok;
Cloudflare Tunnel;
localtunnel;
Smee;
Stripe CLI;
GitHub CLI o utilidades asociadas.

Los túneles de desarrollo no deben utilizarse como infraestructura de producción salvo que se encuentren diseñados y administrados para ese propósito.

Captura de solicitudes

Servicios como Webhook.site generan una URL temporal y muestran:

encabezados;
cuerpo;
método;
hora;
dirección de origen.

Son útiles para comprender el payload, aunque no deben recibir datos sensibles reales sin revisar sus políticas.

Fixtures

Los payloads de prueba deben almacenarse como archivos versionados.

Ejemplo:

<syntaxhighlight lang="text"> fixtures/

 payment_succeeded.json
 payment_failed.json
 subscription_cancelled.json

</syntaxhighlight>

Pruebas unitarias

Validan:

cálculo de firma;
parsing;
selección de manejador;
idempotencia;
transiciones.

Pruebas de integración

Comprueban:

endpoint;
base de datos;
cola;
workers;
servicios externos.

Pruebas de contrato

Verifican que el consumidor continúe siendo compatible con el esquema del productor.

Pruebas de replay

Reenvían entregas históricas dentro de un entorno controlado.

Pruebas de carga

Simulan picos de eventos.

Pruebas de caos

Introducen:

lentitud;
colas detenidas;
base inaccesible;
duplicados;
eventos desordenados;
errores temporales.

Observabilidad

Una integración necesita visibilidad sobre cada etapa.

Métricas del endpoint

solicitudes recibidas;
firmas inválidas;
payloads inválidos;
latencia;
códigos de respuesta;
tamaño;
timeouts.

Métricas de cola

profundidad;
edad del evento más antiguo;
tasa de procesamiento;
reintentos;
mensajes muertos.

Métricas de negocio

pagos procesados;
leads creados;
pedidos actualizados;
mensajes entregados;
conversiones registradas.

Logs estructurados

Un registro puede incluir:

<syntaxhighlight lang="json"> {

 "event_id": "evt_01JXYZ",
 "delivery_id": "del_550",
 "provider": "payment_platform",
 "event_type": "payment.succeeded",
 "status": "processed",
 "attempt": 1,
 "duration_ms": 82

} </syntaxhighlight>

Correlation ID

Permite seguir una operación entre:

webhook;
cola;
worker;
CRM;
correo;
analítica.

Alertas

Se pueden generar alertas cuando:

aumenta la tasa de firmas inválidas;
el endpoint devuelve errores;
la cola crece;
los eventos permanecen pendientes;
se acumulan mensajes muertos;
deja de recibirse un evento esperado.

La ausencia de eventos también puede indicar una falla.

Aplicaciones en marketing

Generación de leads

Un formulario puede enviar un evento cuando una persona solicita información.

El webhook puede:

crear un contacto;
registrar UTM;
asignar vendedor;
enviar confirmación;
iniciar una secuencia;
notificar al equipo.

Ejemplo:

<syntaxhighlight lang="json"> {

 "id": "evt_lead_501",
 "type": "lead.created",
 "data": {
   "lead_id": "LEAD-501",
   "name": "Ana Pérez",
   "phone": "5555555555",
   "source": "facebook_ads",
   "campaign": "baterias_tijuana"
 }

} </syntaxhighlight>

CRM

Los webhooks permiten mantener sincronizados:

contactos;
empresas;
oportunidades;
actividades;
estados;
propietarios;
notas.

Un cambio dentro del CRM puede activar una acción en otra plataforma.

Automatización de marketing

Los webhooks funcionan como disparadores y acciones dentro de flujos.

Ejemplo:

<syntaxhighlight lang="text"> Formulario enviado → webhook → n8n → validar teléfono → crear contacto → etiquetar campaña → enviar WhatsApp → avisar al vendedor </syntaxhighlight>

Email marketing

Las plataformas pueden informar:

suscripción;
apertura;
clic;
rebote;
queja;
baja;
entrega.

Estos eventos pueden actualizar el CRM y evitar nuevos envíos hacia direcciones inválidas.

Publicidad digital

Los webhooks pueden activar procesos relacionados con:

leads de anuncios;
conversiones;
audiencias;
estados de campañas;
moderación;
formularios instantáneos.

Los datos enviados hacia plataformas publicitarias deben cumplir consentimiento, minimización y políticas del proveedor.

Comercio electrónico

Los eventos pueden incluir:

pedido creado;
pago confirmado;
carrito abandonado;
producto actualizado;
inventario modificado;
pedido enviado;
devolución.

Pagos

Los sistemas comerciales deben depender de eventos confirmados por el proveedor y no exclusivamente de una redirección del navegador.

El usuario puede cerrar la página, perder conexión o manipular parámetros.

El webhook permite que el backend reciba el estado real de la transacción.

Suscripciones

Los eventos pueden comunicar:

inicio;
renovación;
pago fallido;
cambio de plan;
cancelación;
periodo de gracia;
factura.

WhatsApp y mensajería

Las plataformas de mensajería utilizan webhooks para informar:

mensaje recibido;
mensaje entregado;
mensaje leído;
error;
cambio de plantilla;
estado de cuenta.

El receptor puede conectar la conversación con CRM, bots y agentes humanos.

Chatbots

Un webhook permite que el bot consulte inventario, cree pedidos, busque clientes o solicite acciones externas.

Agentes de inteligencia artificial

Un webhook puede activar un agente cuando:

llega un correo;
cambia una oportunidad;
se publica un artículo;
ocurre una compra;
se recibe un documento.

El agente puede procesar el evento y utilizar herramientas bajo permisos controlados.

SEO

Un gestor de contenidos puede enviar un webhook cuando se publica o actualiza una página.

El receptor puede:

purgar caché;
regenerar la página;
actualizar sitemap;
solicitar indexación cuando la plataforma lo permite;
ejecutar una auditoría;
comprobar enlaces.

Headless CMS

Los webhooks notifican cambios de:

contenidos;
activos;
autores;
categorías;
publicaciones.

El frontend puede reconstruir únicamente las páginas afectadas.

Marketing local

Un cambio en horarios, inventario, sucursal o zona de servicio puede propagarse hacia diferentes sitios y directorios.

Reservaciones

Los eventos pueden actualizar calendarios, CRM, recordatorios y disponibilidad.

Eventos presenciales

Los webhooks pueden informar:

registro;
pago;
check-in;
asistencia;
cancelación;
certificado.

Fidelización

Una compra puede activar:

suma de puntos;
cambio de nivel;
recompensa;
aviso;
cupón.

Afiliación

Los eventos pueden registrar:

clic;
conversión;
comisión;
cancelación;
pago.

Analítica server-side

Una compra confirmada puede enviarse hacia sistemas analíticos desde el backend.

Esto reduce dependencia del navegador, aunque no elimina obligaciones de privacidad.

Social listening

Determinadas plataformas pueden enviar menciones, comentarios y mensajes cuando ocurren.

Automatización editorial

Un evento de publicación puede:

generar versiones sociales;
producir un resumen;
avisar al equipo;
crear tareas;
actualizar feeds.

Ventajas del concepto

Entrega cercana al tiempo real. Los cambios se comunican rápidamente.

Reducción de polling. Disminuyen consultas sin resultados.

Menor consumo de cuotas. Se evita utilizar la API continuamente.

Automatización. Los eventos activan procesos sin intervención manual.

Desacoplamiento. El productor puede notificar sin controlar toda la lógica del receptor.

Escalabilidad funcional. Un evento puede alimentar múltiples procesos.

Integración accesible. HTTP y JSON se encuentran ampliamente soportados.

Respuesta a procesos asíncronos. Resultan adecuados para pagos, entregas y suscripciones.

Sincronización. Mantienen sistemas relacionados con mayor actualidad.

Trazabilidad. Los Event IDs permiten seguir cambios.

Extensibilidad. Se pueden añadir consumidores sin modificar el flujo principal.

Compatibilidad con no-code. Las plataformas visuales pueden recibir y enviar webhooks.

Automatización de marketing. Facilitan conectar herramientas heterogéneas.

Reducción de latencia comercial. Un lead puede asignarse inmediatamente.

Experiencia del cliente. Los avisos y estados pueden actualizarse rápidamente.

Limitaciones

Ausencia de estándar universal. Cada proveedor utiliza contratos diferentes.

Duplicados. Un mismo evento puede entregarse varias veces.

Desorden. Los eventos pueden llegar en una secuencia distinta.

Pérdida potencial. Algunos proveedores no reintentan automáticamente.

Dependencia de disponibilidad. El endpoint debe estar accesible.

Seguridad. Una URL pública recibe tráfico no confiable.

Complejidad de firmas. Cada proveedor utiliza encabezados y algoritmos propios.

Timeouts. Los procesos lentos pueden provocar reintentos.

Depuración distribuida. Los errores atraviesan varios sistemas.

Versionado. Un cambio del proveedor puede romper el consumidor.

Privacidad. Los payloads pueden contener datos personales.

Costos de picos. Una campaña o migración puede generar miles de eventos.

Consistencia eventual. Los sistemas pueden mostrar estados temporales diferentes.

Dependencia de proveedor. Las políticas de reintento y retención varían.

Dificultad para reproducir errores. Algunos eventos dependen de condiciones reales.

Cadenas frágiles. Un webhook que activa varios más puede multiplicar fallos.

Observabilidad necesaria. Sin registros, los eventos pueden perderse silenciosamente.

Limitaciones de filtros. Algunos proveedores envían más información de la necesaria.

Entrega exactamente una vez impráctica. El receptor debe diseñarse para duplicados.

Consideraciones técnicas o estadísticas

Latencia

Puede medirse desde:

momento del evento;
creación de la entrega;
llegada al endpoint;
encolado;
procesamiento;
finalización comercial.

Métricas útiles:

p50;
p95;
p99;
máximo;
edad del evento.

Disponibilidad

El endpoint puede establecer un objetivo de disponibilidad.

Una disponibilidad de 99.9 % permite aproximadamente 43 minutos de indisponibilidad mensual, aunque el efecto real depende de reintentos y retención.

Throughput

Representa eventos recibidos por segundo o minuto.

Debe estimarse para:

promedio;
pico;
campañas;
reenvíos masivos;
recuperación después de una caída.

Tamaño del payload

Los límites deben definirse en bytes.

Los eventos con objetos completos pueden consumir ancho de banda y memoria.

Tiempo de respuesta

Conviene responder antes del timeout del proveedor.

GitHub recomienda responder dentro de un periodo breve y delegar el procesamiento, mientras otros proveedores establecen sus propios límites.

Tasa de éxito

<syntaxhighlight lang="text"> entregas exitosas / entregas totales </syntaxhighlight>

Tasa de duplicados

<syntaxhighlight lang="text"> eventos repetidos / eventos recibidos </syntaxhighlight>

Retries por evento

Permite identificar endpoints inestables.

Edad de cola

Indica cuánto tiempo lleva esperando el evento más antiguo.

Tasa de dead letters

Mide eventos enviados a revisión manual.

Tiempo de recuperación

Periodo entre una falla y el procesamiento completo de eventos pendientes.

Conversión comercial

Puede medirse el tiempo desde un evento de lead hasta:

asignación;
primer contacto;
respuesta;
venta.

Costo

Incluye:

infraestructura;
transferencia;
colas;
almacenamiento;
observabilidad;
soporte;
reintentos;
servicios de automatización.

Herramientas y plataformas

GitHub Webhooks. Notifican eventos relacionados con repositorios, organizaciones y aplicaciones.

Stripe Webhooks. Informan pagos, facturas, suscripciones, disputas y otros eventos financieros.

Shopify Webhooks. Comunican cambios de tiendas, pedidos, productos, clientes e inventarios.

WooCommerce Webhooks. Permiten activar entregas ante cambios del comercio electrónico.

PayPal Webhooks. Informan transacciones, pagos, disputas y suscripciones.

Twilio Webhooks. Se utilizan para llamadas, SMS, WhatsApp y otros servicios de comunicación.

Meta Webhooks. Proporcionan eventos para productos y plataformas de Meta.

Slack Events API. Envía eventos relacionados con espacios, mensajes y aplicaciones.

Discord Webhooks. Permiten publicar mensajes y automatizaciones hacia canales.

HubSpot Webhooks. Notifican cambios en objetos del CRM y aplicaciones.

Salesforce Platform Events y webhooks. Permiten integraciones orientadas a eventos.

Mailchimp Webhooks. Informan cambios de suscriptores y campañas.

SendGrid Event Webhook. Comunica entregas, rebotes, aperturas, clics y bajas.

n8n. Proporciona nodos webhook para iniciar y conectar flujos.

Zapier Webhooks. Permite recibir y enviar solicitudes dentro de automatizaciones.

Make Webhooks. Crea disparadores instantáneos y flujos.

IFTTT Webhooks. Conecta eventos simples entre servicios.

Pipedream. Permite recibir eventos, ejecutar código y conectar API.

Webhook.site. Genera URLs temporales para inspeccionar solicitudes.

ngrok. Expone servicios locales mediante túneles.

Cloudflare Tunnel. Conecta servicios locales o privados sin publicar directamente puertos.

Smee. Reenvía payloads hacia entornos de desarrollo.

Stripe CLI. Escucha y reenvía eventos de Stripe durante desarrollo.

Postman. Permite enviar payloads y probar endpoints.

Insomnia. Cliente para solicitudes y API.

curl. Herramienta de línea de comandos para simular entregas.

RequestBin. Denominación utilizada por servicios de captura de solicitudes.

Hookdeck. Plataforma para gestionar, observar y reenviar webhooks.

Svix. Infraestructura para enviar y administrar webhooks.

Convoy. Gateway abierto para entregas y observabilidad.

Amazon EventBridge. Bus administrado capaz de recibir eventos de distintos proveedores.

Azure Event Grid. Servicio de distribución de eventos.

Google Cloud Pub/Sub. Plataforma de mensajería y eventos.

RabbitMQ. Broker de mensajes utilizado después de la recepción.

Apache Kafka. Plataforma distribuida para flujos de eventos.

OpenAPI. Permite documentar contratos de webhook.

CloudEvents. Estandariza atributos de eventos.

JSON Schema. Valida payloads.

OpenTelemetry. Facilita métricas, logs y trazas.

Sentry. Registra errores y rendimiento.

Grafana y Prometheus. Proporcionan observabilidad y alertas.

Relación con otros conceptos

API. Interfaz que permite consultar y modificar recursos.

REST. Estilo arquitectónico utilizado frecuentemente en endpoints.

HTTP. Protocolo mediante el cual se entregan numerosos webhooks.

HTTPS. Protege la conexión mediante TLS.

JSON. Formato predominante de payloads.

XML. Formato utilizado por determinadas integraciones.

Callback. Función o destino ejecutado después de un acontecimiento.

Polling. Consultas periódicas para detectar novedades.

Long polling. Solicitud mantenida abierta mientras se esperan eventos.

WebSocket. Conexión bidireccional persistente.

Server-Sent Events. Canal unidireccional continuo desde servidor a navegador.

Arquitectura orientada a eventos. Modelo basado en productores, eventos y consumidores.

Publish-subscribe. Patrón donde consumidores se suscriben a eventos.

Cola de mensajes. Sistema que almacena y distribuye trabajos.

Event bus. Infraestructura que enruta eventos.

CloudEvents. Especificación común para describir eventos.

OpenAPI. Estándar de documentación de interfaces HTTP.

HMAC. Mecanismo de autenticación e integridad mediante hash y secreto.

Idempotencia. Prevención de efectos duplicados.

Consistencia eventual. Convergencia posterior entre sistemas.

Microservicios. Arquitectura donde servicios pueden comunicarse mediante eventos.

Serverless. Funciones que pueden activarse mediante webhooks.

Automatización. Ejecución programática de tareas.

Automatización de marketing. Conexión de eventos comerciales con acciones.

CRM. Sistema que recibe y produce eventos de contactos y ventas.

E-commerce. Utiliza webhooks para pedidos, pagos e inventarios.

Marketing conversacional. Usa webhooks para mensajes, estados y bots.

Agentes de inteligencia artificial. Pueden activarse mediante eventos externos.

Model Context Protocol. Protocolo para conectar modelos con herramientas y recursos.

Middleware. Capa intermedia que transforma, valida y enruta solicitudes.

Integración de sistemas. Disciplina que conecta aplicaciones y datos.

Diferencias entre webhook y API

Una API tradicional espera que el consumidor inicie la solicitud.

Un webhook permite que el productor envíe una notificación cuando ocurre un evento.

API:

<syntaxhighlight lang="text"> Consumidor → consulta → Proveedor </syntaxhighlight>

Webhook:

<syntaxhighlight lang="text"> Proveedor → evento → Consumidor </syntaxhighlight>

Ambos mecanismos suelen utilizarse conjuntamente.

El webhook informa que ocurrió un cambio y la API permite consultar detalles o ejecutar acciones.

Diferencias entre webhook y polling

El polling realiza consultas periódicas.

Ventajas:

control del momento;
implementación sencilla;
recuperación directa del estado actual.

Limitaciones:

solicitudes innecesarias;
latencia definida por el intervalo;
consumo de cuota.

El webhook envía cambios conforme ocurren.

Ventajas:

menor latencia;
menos consultas;
reacción inmediata.

Limitaciones:

endpoint público;
duplicados;
reintentos;
necesidad de observabilidad.

Una integración robusta puede utilizar webhooks para cambios y polling periódico para reconciliación.

Diferencias entre webhook y WebSocket

Un webhook utiliza solicitudes independientes iniciadas por un servidor.

WebSocket mantiene una conexión bidireccional persistente.

Los webhooks resultan adecuados para:

eventos ocasionales;
comunicación servidor a servidor;
integración entre plataformas.

WebSocket resulta útil para:

chat;
colaboración;
juegos;
actualizaciones continuas;
baja latencia bidireccional.

Diferencias entre webhook y Server-Sent Events

Server-Sent Events mantiene una conexión HTTP abierta mediante la cual el servidor envía múltiples eventos al navegador.

Un webhook realiza solicitudes separadas hacia un endpoint servidor.

SSE se orienta principalmente a actualizaciones continuas dentro de clientes web.

Diferencias entre webhook y cola de mensajes

Una cola almacena mensajes dentro de una infraestructura de mensajería.

Un webhook entrega una solicitud directamente hacia una URL.

Las colas suelen proporcionar:

mayor durabilidad;
consumidores internos;
control de backpressure;
semánticas avanzadas.

Los webhooks ofrecen:

integración abierta;
compatibilidad HTTP;
menor barrera para terceros.

Un endpoint puede recibir el webhook y publicarlo inmediatamente dentro de una cola.

Diferencias entre webhook y evento

El evento representa el hecho ocurrido.

El webhook es uno de los mecanismos utilizados para transportarlo.

Un mismo evento puede enviarse mediante:

webhook;
cola;
bus;
streaming;
almacenamiento.

Diferencias entre webhook y callback URL

Una callback URL es una dirección donde una aplicación espera una llamada posterior.

Puede utilizarse para:

OAuth;
pagos;
tareas asíncronas;
webhooks.

Todo endpoint de webhook funciona como callback HTTP, aunque no toda callback URL representa una suscripción persistente a eventos.

Buenas prácticas

Suscribirse solamente a eventos necesarios. Reduce carga y exposición.

Utilizar HTTPS. Protege el transporte.

Verificar firmas antes de procesar. Confirma origen e integridad.

Conservar el cuerpo original. Evita errores de verificación.

Comprobar timestamps. Reduce ataques de replay.

Usar comparación de tiempo constante. Protege la validación criptográfica.

Almacenar secretos en un gestor seguro. Evita filtraciones.

Rotar secretos. Limita el impacto de una exposición.

Implementar idempotencia. Los duplicados no deben producir efectos adicionales.

Registrar Event IDs. Facilita deduplicación y trazabilidad.

Responder rápidamente. El trabajo pesado debe ejecutarse en segundo plano.

Utilizar colas. Aísla recepción y procesamiento.

Definir timeouts internos. Las dependencias no deben bloquear workers.

Aplicar reintentos con backoff. Los errores temporales necesitan recuperación controlada.

Crear dead-letter queue. Los eventos fallidos deben conservarse.

Validar el esquema. Los payloads mal formados deben rechazarse o aislarse.

Ignorar campos desconocidos de manera segura. Facilita evolución compatible.

Comprobar tipo y acción. Evita procesar eventos incorrectos.

No confiar en el orden. Se debe consultar o comparar el estado.

Consultar la API cuando resulte necesario. Permite confirmar el estado actual.

Aplicar límites de tamaño. Protege memoria y procesamiento.

Aplicar rate limiting. Reduce abuso sin bloquear picos válidos.

Registrar códigos y tiempos. Facilita diagnóstico.

Incluir correlation IDs. Permite rastrear procesos distribuidos.

Probar duplicados y desorden. Representan condiciones normales.

Simular caídas. Verifica reintentos y recuperación.

Mantener fixtures versionados. Facilita pruebas de regresión.

Documentar versiones. El contrato debe ser visible para equipos consumidores.

Implementar reconciliación. Una tarea periódica puede detectar eventos faltantes.

No devolver datos sensibles. La respuesta debe ser mínima.

Separar endpoints por proveedor cuando convenga. Facilita seguridad y monitoreo.

Auditar suscripciones. Los endpoints abandonados deben eliminarse.

Monitorear ausencia de eventos. El silencio inesperado puede ser una falla.

Cumplir políticas de privacidad. Deben enviarse solamente datos necesarios.

Errores comunes

Procesar antes de verificar la firma. Permite solicitudes falsificadas.

Analizar JSON antes de conservar el cuerpo. Puede invalidar la firma.

Utilizar un secreto corto o predecible. Reduce seguridad.

Guardar el secreto dentro del repositorio. Puede quedar expuesto en el historial.

Aceptar eventos sin timestamp. Aumenta riesgo de replay cuando el proveedor permite firmarlo.

Confiar exclusivamente en la dirección IP. No demuestra integridad del contenido.

Procesar dos veces el mismo Event ID. Puede duplicar pedidos, mensajes o puntos.

Asumir entrega exactamente una vez. No corresponde con la realidad de numerosas plataformas.

Asumir orden cronológico. Los reintentos pueden alterar la secuencia.

Ejecutar tareas lentas antes de responder. Produce timeouts y duplicados.

Responder 200 antes de almacenar el evento. Puede perderse si el proceso falla después.

No disponer de cola. Los picos pueden saturar el endpoint.

No limitar el tamaño del cuerpo. Facilita denegación de servicio.

Aceptar cualquier Content-Type. Puede provocar parsing inesperado.

Registrar payloads completos con datos personales. Aumenta exposición.

Usar una URL sin autenticación o firma. Cualquier persona podría enviar solicitudes.

Incluir secretos en query strings. Pueden aparecer en logs.

No controlar redirecciones. Puede desviar solicitudes y secretos.

No validar el tenant. Un evento legítimo podría aplicarse a la cuenta incorrecta.

No gestionar versiones. Una actualización del proveedor rompe el parser.

Depender de campos opcionales. El procesamiento falla cuando se omiten.

No registrar eventos fallidos. Desaparecen sin posibilidad de recuperación.

Reintentar sin idempotencia. Duplica efectos.

Reintentar permanentemente errores definitivos. Consume recursos sin resolver el problema.

No establecer una dead-letter queue. Los eventos problemáticos bloquean la cola.

Encadenar demasiados webhooks. Aumenta fragilidad.

Utilizar una herramienta de pruebas en producción. Puede exponer información.

Confiar en que todos los proveedores reintentan. Algunos requieren redelivery manual.

No probar la rotación del secreto. Puede interrumpir todas las entregas.

No desactivar endpoints obsoletos. Mantiene superficies de ataque.

Desafíos éticos y organizacionales

Privacidad. Los payloads pueden contener datos personales, financieros y conductuales.

Minimización. El productor debe enviar únicamente información necesaria.

Consentimiento. Los datos de marketing deben utilizarse para finalidades autorizadas.

Trazabilidad. La organización necesita conocer qué sistemas reciben cada evento.

Retención. Los eventos pueden permanecer en logs, colas y respaldos durante periodos extensos.

Eliminación. Las solicitudes de borrado deben considerar copias e integraciones.

Shadow integrations. Los equipos pueden crear webhooks sin revisión de seguridad.

Dependencia de plataformas. Las automatizaciones pueden quedar ligadas a contratos propietarios.

Responsabilidad. Debe definirse quién atiende fallos y datos incorrectos.

Automatización de decisiones. Un evento puede activar acciones comerciales sensibles sin revisión.

Errores a escala. Una configuración incorrecta puede duplicar miles de mensajes o cobros.

Vigilancia. La transmisión de cada acción puede convertirse en seguimiento excesivo.

Seguridad de terceros. El productor envía datos hacia infraestructura que no controla.

Soberanía de datos. Los endpoints pueden encontrarse en otras jurisdicciones.

Transparencia. Los usuarios pueden desconocer cuántas aplicaciones reciben su información.

Sostenibilidad. Los eventos redundantes consumen procesamiento, almacenamiento y red.

Una política organizacional puede establecer:

catálogo de webhooks;
propietarios;
proveedores autorizados;
clasificación de datos;
secretos;
retención;
versiones;
monitoreo;
reintentos;
respuesta a incidentes;
retiro.

Gobernanza organizacional

Cada webhook debería documentar:

nombre;
propósito;
productor;
consumidor;
propietario;
URL;
eventos;
datos;
secreto;
algoritmo;
versión;
política de reintentos;
timeout;
retención;
métricas;
alertas;
procedimiento de recuperación.

Los endpoints pueden clasificarse por riesgo.

Riesgo bajo. Notificaciones sin datos sensibles y sin acciones destructivas.

Riesgo moderado. Sincronización de contenidos o contactos.

Riesgo alto. Pedidos, pagos, accesos, campañas y mensajería.

Riesgo crítico. Movimientos financieros, permisos, infraestructura y decisiones reguladas.

Los niveles elevados requieren:

firma;
allowlist adicional;
mTLS cuando corresponda;
auditoría;
revisión de código;
pruebas de carga;
reconciliación;
monitoreo continuo.

Impacto actual

Los webhooks constituyen una infraestructura fundamental de la economía de API y de la automatización empresarial.

Permiten que miles de plataformas reaccionen ante cambios sin construir conexiones persistentes ni ejecutar polling constante.

Su adopción ha favorecido el desarrollo de ecosistemas donde una aplicación puede activar procesos dentro de múltiples herramientas.

Las plataformas de no-code han convertido los webhooks en una interfaz accesible para personas que no desarrollan integraciones completas mediante código.

Un usuario puede copiar una URL, registrarla dentro de una plataforma y utilizar los datos recibidos para iniciar un flujo.

Esta facilidad también aumenta la cantidad de integraciones sin documentación, seguridad u observabilidad.

En pagos y comercio electrónico, los webhooks resultan esenciales porque numerosas operaciones se completan de forma asíncrona.

En marketing, reducen el tiempo entre una acción del usuario y la respuesta comercial. Un lead puede llegar al CRM y asignarse en segundos.

En desarrollo de software, activan procesos de integración continua, despliegue, revisión y notificaciones.

En inteligencia artificial, los webhooks permiten que agentes y flujos generativos reaccionen ante eventos reales.

La evolución hacia destinos de eventos administrados muestra que los webhooks forman parte de una categoría más amplia de integración orientada a eventos.

Su sencillez continuará siendo valiosa, aunque los sistemas de gran escala necesitan colas, esquemas, seguridad, versionado y gobernanza alrededor del endpoint HTTP.

Futuro y tendencias

Mayor estandarización. CloudEvents y OpenAPI facilitarán contratos interoperables.

Firmas estandarizadas. Crecerá el uso de firmas HTTP y esquemas comunes.

Claves asimétricas. Más proveedores publicarán claves para verificar firmas sin compartir secretos.

Destinos administrados. Los eventos podrán enviarse directamente hacia buses y colas de nube.

Event gateways. Las organizaciones centralizarán validación, filtrado, reintentos y observabilidad.

Esquemas gobernados. Los payloads se registrarán dentro de catálogos de eventos.

Contratos generados. OpenAPI y JSON Schema producirán validadores y simuladores.

Pruebas automáticas de compatibilidad. Los cambios de versión se comprobarán antes del despliegue.

Observabilidad de extremo a extremo. Las trazas seguirán el evento desde el productor hasta el efecto comercial.

Replay controlado. Las plataformas permitirán reproducir periodos completos de eventos.

Filtrado avanzado. Los consumidores recibirán solamente eventos y campos necesarios.

Transformación en el borde. Los gateways adaptarán formatos antes de la entrega.

Mayor protección frente a SSRF. Los productores limitarán destinos y validarán DNS.

Rotación automática de secretos. Las plataformas administrarán periodos de transición.

Privacidad por diseño. Los eventos contendrán referencias o campos minimizados.

Agentes de inteligencia artificial. Los webhooks activarán agentes especializados.

Webhooks generados por lenguaje natural. Las herramientas crearán endpoints y flujos a partir de descripciones.

No-code empresarial. Las automatizaciones visuales incorporarán control de versiones, pruebas y gobernanza.

Reconciliación automática. Los sistemas detectarán y recuperarán eventos faltantes.

Entregas adaptativas. Los productores modificarán frecuencia y lotes según capacidad del consumidor.

Batch webhooks. Los eventos de alto volumen podrán agruparse.

Event streaming complementario. Los consumidores avanzados podrán elegir entre webhook, bus o stream.

Mayor regulación. Las transferencias de datos entre plataformas recibirán controles adicionales.

Gobernanza centralizada. Los webhooks se administrarán como interfaces críticas y no como configuraciones aisladas.

Véase también

Referencias

Bibliografía

Burns, Brendan. Designing Distributed Systems. O’Reilly Media.
Cloud Native Computing Foundation. CloudEvents Specification.
Fowler, Martin. Patterns of Enterprise Application Architecture. Addison-Wesley.
Hohpe, Gregor; Woolf, Bobby. Enterprise Integration Patterns. Addison-Wesley.
Kleppmann, Martin. Designing Data-Intensive Applications. O’Reilly Media.
Krawczyk, Hugo; Bellare, Mihir; Canetti, Ran. HMAC: Keyed-Hashing for Message Authentication. IETF.
Newman, Sam. Building Microservices. O’Reilly Media.
Nygard, Michael T. Release It!. Pragmatic Bookshelf.
OpenAPI Initiative. OpenAPI Specification.
OWASP Foundation. API Security Top 10.
Richardson, Chris. Microservices Patterns. Manning.
Richards, Mark; Ford, Neal. Fundamentals of Software Architecture. O’Reilly Media.
Stripe. Webhooks Documentation.
GitHub. Webhooks Documentation.
Tanenbaum, Andrew S.; Van Steen, Maarten. Distributed Systems. Pearson.
Vinoski, Steve. Advanced Message Queuing Protocol and Event-Driven Integration.
W3C y IETF. HTTP and Web Security Specifications.