¿Qué es un Webhook y Cómo Funciona? Guía Completa para Integraciones Eficientes

Webhook es un mecanismo que permite que un sistema notifique automáticamente a otro sobre un evento ocurrido. En lugar de realizar consultas constantes al servidor, la aplicación recibe los datos justo en el momento en que se producen: por ejemplo, tras un pago exitoso, un nuevo pedido o un cambio en el estado de la entrega.

Los webhooks resultan especialmente útiles para la integración entre varios servicios. Reducen la cantidad de solicitudes innecesarias y permiten reaccionar más rápido ante los cambios. Aunque están estrechamente relacionados con las API tradicionales, los webhooks funcionan bajo un principio diferente.

¿Qué es un webhook y para qué se utilizan?

Webhook explicado de forma sencilla

La diferencia entre una API y un webhook puede entenderse fácilmente con el ejemplo de las notificaciones.

Al trabajar con una API, la aplicación consulta al servidor: "¿Hay datos nuevos?". Si no hay cambios, volverá a preguntar pasado un tiempo.

El webhook funciona de manera opuesta. La aplicación le da previamente al servicio una dirección especial, y el servicio le envía una solicitud justo cuando ocurre el evento necesario.

Por ejemplo, una tienda online no necesita consultar a la pasarela de pago cada pocos segundos para saber si el usuario pagó el pedido. El servicio de pago puede enviar un webhook automáticamente tras la confirmación del pago.

Por eso, los webhooks suelen llamarse mecanismos de notificación entre programas. Un sistema no consulta constantemente el estado del otro, sino que simplemente espera un mensaje sobre el evento relevante.

¿Qué problemas resuelven los webhooks?

El webhook se utiliza donde es necesario reaccionar rápidamente ante cambios en otro servicio. Ejemplos típicos:

• el sistema de pagos informa a la tienda sobre un pago exitoso;
• el CRM recibe información sobre una nueva solicitud desde el sitio web;
• el servicio de mensajería envía el nuevo estado del pedido;
• la plataforma de Git inicia una compilación tras subir código nuevo;
• el mensajero transmite un nuevo mensaje al bot;
• el servicio en la nube notifica la finalización del procesamiento de un archivo.

La clave de estos escenarios es que la acción se activa por un evento. El sistema no verifica el estado a intervalos regulares, sino que recibe una señal solo cuando realmente sucede algo.

Este principio no solo se usa en integraciones puntuales, sino también en sistemas de software más complejos. Puedes leer más sobre ello en el artículo Por qué la arquitectura orientada a eventos hace los sistemas más rápidos y reactivos.

Gracias a esto, el webhook es especialmente útil para la automatización. Tras recibir el evento, el programa puede cambiar el estado de un pedido, notificar al usuario, guardar datos en la base o iniciar otro proceso.

¿Cómo funciona un webhook?

Evento, URL y solicitud HTTP

Para que funcione un webhook, el sistema receptor primero crea una URL especial -el endpoint-. Es en esta dirección donde el otro servicio enviará las notificaciones de eventos.

El esquema es simple:

• evento →
• el servicio genera los datos →
• envía una solicitud HTTP →
• el sistema receptor la procesa.

Por ejemplo, cuando un usuario paga un pedido, el servicio de pagos detecta la transacción exitosa y envía una solicitud HTTP al webhook de la tienda online. Al recibirla, la tienda cambia el estado del pedido a "Pagado" y puede iniciar acciones posteriores automáticamente.

La mayoría de los webhooks usan el método HTTP POST, ya que es necesario transferir datos sobre el evento junto con la solicitud. Sin embargo, el formato exacto depende del servicio: algunas plataformas pueden usar otros métodos HTTP.

¿Qué contiene una solicitud webhook?

Una solicitud webhook suele incluir varias partes. La URL indica la dirección del manejador, los encabezados HTTP pueden transmitir datos técnicos, y la información principal del evento se encuentra en el cuerpo de la solicitud.

En muchos servicios los datos se envían en formato JSON. Por ejemplo, una notificación de pago puede incluir el identificador del pedido, monto, moneda, estado del pago y el momento de la operación.

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

Al recibir esta solicitud, la aplicación lee el campo event, determina el tipo de evento y ejecuta la lógica necesaria. Si el evento es de pago, el pedido puede marcarse como pagado; si es de entrega, se actualiza el estado.

Tras procesar el webhook, el servidor suele devolver un código de respuesta HTTP. Un código 200 indica que la solicitud fue recibida con éxito. Si el servidor responde con error o no responde, el servicio emisor puede intentar reenviar el evento.

Ejemplo práctico de webhook

Imagina una tienda online conectada a un sistema de pagos externo.

El cliente realiza el pedido y pasa a la página de pago. Tras el pago, el servicio de pagos recibe la confirmación del banco, pero la tienda aún no sabe el resultado.

En lugar de que la tienda consulte constantemente el estado del pago vía API, el sistema de pagos envía un webhook:

payment.success → webhook de la tienda → cambio de estado del pedido

El servidor de la tienda recibe la notificación, verifica los datos y automáticamente cambia el pedido a "Pagado". A partir de ahí, puede enviar el recibo, notificar al almacén y preparar el producto para el envío.

Este enfoque es especialmente útil en procesos donde el evento puede ocurrir segundos, minutos o incluso horas después de la solicitud inicial. La aplicación no necesita comprobar el estado todo ese tiempo: solo espera el webhook.

Webhook y API: ¿en qué se diferencian?

La API funciona por consulta, el webhook por evento

La principal diferencia entre webhook y una API tradicional es quién inicia el intercambio de datos.

Con la API, la aplicación envía la solicitud al servidor. Por ejemplo, el cliente puede pedir la lista de pedidos, ver el perfil de usuario o consultar el estado del pago. El servidor responde solo tras esa consulta.

El webhook opera con una lógica distinta. El receptor informa de antemano su URL, y el servicio fuente envía la solicitud cuando ocurre el evento necesario.

Esto puede verse como dos modelos:

• API - "preguntar si pasó algo";
• webhook - "recibir un mensaje cuando pase algo".

En la documentación técnica, estos enfoques se asocian a los modelos pull y push. La API se usa para el mecanismo pull (el cliente solicita los datos), mientras que el webhook es push (los datos llegan automáticamente al receptor).

Webhook vs REST API

Ambos, webhook y REST API, usan las mismas tecnologías clave de Internet: HTTP, URL, encabezados, métodos de solicitud y formatos como JSON. Pero su propósito varía.

Por ejemplo, a través de la API la tienda puede consultar información sobre un pago concreto. Por webhook, el sistema de pago informa a la tienda cuando ese pago se completa con éxito.

Por eso, comparar webhook y API como tecnologías excluyentes no es del todo correcto.

El webhook no reemplaza a la API

En la práctica, webhook y API suelen trabajar juntos.

La API se usa cuando el programa necesita obtener o modificar datos por sí mismo. El webhook sirve para enterarse rápidamente de un evento ocurrido.

Por ejemplo, en un CRM, la aplicación puede obtener la ficha de un cliente, modificar su teléfono o consultar el historial de pedidos mediante la API. El webhook, en cambio, puede notificar a un sistema externo cuando aparece un nuevo cliente o cambia la etapa de una oportunidad.

En ocasiones, el webhook solo transmite información mínima: el ID del objeto y el tipo de evento. La aplicación luego consulta la API para obtener el resto de los datos.

Así se evita el envío constante de solicitudes y se mantiene la flexibilidad de la API tradicional.

¿Cuándo usar webhook y cuándo usar la API tradicional?

Cuándo es más conveniente el webhook

El webhook es ideal cuando el sistema necesita conocer un evento justo después de que suceda.

Ejemplos típicos: confirmación de pago, creación de un nuevo pedido, cambio de estado en la entrega, aparición de un nuevo lead en el CRM, carga de archivos o publicación de código en un repositorio.

En estos casos, las consultas periódicas a la API generan carga innecesaria. Si la aplicación pregunta cada minuto si cambió el estado de un pedido, la mayoría de las veces la respuesta será la misma. El webhook elimina esta necesidad: la solicitud se envía solo tras un cambio real.

Por eso, los webhooks son especialmente útiles para la automatización de procesos y la integración de servicios que deben reaccionar casi en tiempo real.

Cuándo es mejor usar la API

La API tradicional es más conveniente si la aplicación debe obtener datos en cualquier momento.

Por ejemplo, cuando un usuario entra a su perfil en la tienda online y quiere ver sus pedidos, la aplicación solicita a la API la lista actualizada.

La API también es necesaria cuando el sistema debe:

• realizar búsquedas;
• obtener listas de objetos;
• crear o modificar registros;
• eliminar datos;
• consultar información detallada por identificador;
• elegir cuándo comunicarse con el servidor.

El webhook no está pensado para estas tareas: solo informa de un evento, pero normalmente no permite pedir información arbitraria bajo demanda.

En la práctica, es común una combinación: el webhook informa de un cambio y luego la aplicación recurre a la API para obtener los datos necesarios.

Webhook, polling y WebSocket

El webhook no es la única forma de recibir actualizaciones de otro servicio. Según la necesidad, se pueden usar polling y WebSocket.

Polling son consultas periódicas al servidor. Por ejemplo, cada diez segundos la aplicación pregunta a la API si hay mensajes nuevos. Es fácil de implementar, pero muchas consultas repetidas consumen recursos incluso si no hay cambios.

El webhook no crea una conexión permanente. El servicio envía una solicitud HTTP solo después de un evento predefinido. Es ideal para integraciones entre servidores, notificaciones y automatización.

WebSocket crea una conexión bidireccional y duradera entre cliente y servidor. Ambas partes pueden intercambiar datos en cualquier momento. Es útil para chats, juegos online, terminales de trading y otras aplicaciones que requieren intercambio continuo en tiempo real.

Más detalles sobre la conexión permanente en el artículo WebSocket explicado: cómo funciona la tecnología de intercambio de datos en tiempo real.

La elección depende del tipo de datos. Si la aplicación decide cuándo solicitar información, lo adecuado es una API. Si se debe reaccionar automáticamente a eventos, se recomienda un webhook. Para flujos de datos bidireccionales en tiempo real, lo mejor es WebSocket.

Cómo configurar un webhook y aspectos clave a tener en cuenta

Creación del endpoint de webhook

Para que funcione el webhook, el sistema receptor necesita una URL pública a la que el servicio externo pueda enviar solicitudes HTTP: el endpoint de webhook.

El desarrollador crea un manejador que recibe los datos entrantes, los valida y ejecuta la acción necesaria. Luego, esta URL se especifica en la configuración del servicio fuente.

Por ejemplo, el endpoint podría ser:

https://example.com/webhooks/payment

Cuando ocurre el evento, el servicio envía la solicitud justo a esa dirección.

Es importante que el endpoint sea accesible desde Internet y soporte HTTPS. Para desarrollo local, a menudo se usan túneles especiales o servicios de pruebas que proporcionan una dirección pública temporal para el desarrollador.

Verificación de la autenticidad del webhook

El endpoint de webhook está abierto a solicitudes entrantes, por lo que no se debe dar por confiable cualquier petición recibida.

Si un atacante descubre la dirección del webhook, podría intentar enviar eventos falsos. Por eso, muchos servicios firman las solicitudes webhook con una clave secreta.

El sistema receptor recibe la solicitud, calcula la firma y la compara con la que envió el servicio. Si coinciden, se confirma que la información proviene del origen esperado y no ha sido alterada.

Adicionalmente, pueden usarse tokens secretos, verificación HTTPS y restricciones de IP, si el servicio lo permite.

Reintentos y duplicados de eventos

El webhook no garantiza que la solicitud siempre se procese exitosamente al primer intento. El servidor podría estar temporalmente fuera de línea, la conexión puede fallar o el procesamiento tardar demasiado.

Por ello, muchas plataformas implementan un mecanismo de reintentos (retry). Si el endpoint devuelve un error o no responde a tiempo, el servicio reenvía la solicitud más tarde.

Esto puede provocar que el mismo evento llegue varias veces. La aplicación debe ser capaz de reconocer duplicados y evitar ejecutar la misma operación más de una vez.

Esto es especialmente importante en pagos: si el webhook de pago exitoso se recibe dos veces, el sistema no debe acreditar el saldo ni crear pedidos duplicados o enviar el producto dos veces.

Para esto, suele usarse un identificador de evento. Antes de actuar, la aplicación verifica si ya ha procesado ese ID antes. A este proceso se le llama manejo idempotente.

Logs y códigos de respuesta

Tras recibir un webhook, el servidor debe devolver un código HTTP de respuesta. Normalmente, el código 200 confirma el procesamiento exitoso.

Si el servidor responde con error, el servicio externo puede considerar que la entrega falló y reintentar la solicitud.

No siempre conviene realizar todo el procesamiento pesado dentro del endpoint del webhook. Si la operación es lenta, conviene validar rápidamente el evento, ponerlo en una cola de tareas, devolver una respuesta exitosa y continuar el trabajo aparte.

El registro de logs también es importante. Es recomendable guardar la hora de recepción, el tipo de evento, el identificador y el resultado del procesamiento. Esto ayuda a entender por qué una notificación no se procesó o por qué el servicio la reenvió.

Un webhook correctamente configurado no es solo una URL para recibir POST. Una integración fiable debe considerar la comprobación de origen, reenvíos, duplicados, errores y caídas temporales del servidor.

Conclusión

El webhook permite que un sistema notifique automáticamente a otro sobre un evento sin realizar verificaciones constantes mediante API. Es especialmente útil para pagos, notificaciones, integraciones entre servicios, automatización y procesos donde es importante reaccionar rápidamente a los cambios.

La principal diferencia entre el webhook y una API tradicional es la dirección de la interacción. Con una API, el cliente solicita los datos; con un webhook, el servicio fuente notifica tras el evento. Sin embargo, el webhook no reemplaza la API: en la mayoría de los casos, ambas tecnologías se usan juntas.

Si el sistema necesita obtener datos bajo demanda, buscar o modificar objetos, la API es adecuada. Si debe reaccionar automáticamente a eventos concretos, lo ideal es el webhook. Para intercambios de datos bidireccionales en tiempo real, se usa WebSocket.

Al implementar un webhook es importante considerar no solo el envío de la solicitud HTTP, sino también la seguridad, la verificación de la firma, los reintentos, la protección ante duplicados y el correcto manejo de errores. Estos detalles convierten un simple endpoint de webhook en una integración robusta entre servicios.