Qué es un webhook y por qué está en todas partes

Publicado el 2026-09-12 por frfrand

En lugar de preguntar cada cinco minutos, el otro servicio te avisa. Cómo funciona, por qué siempre hay que verificar la firma, y los tres detalles que rompen integraciones en producción.

Sin webhooks, la única forma de enterarte de algo que pasa en otro servicio es preguntar: cada minuto, cada cinco, cada hora. Eso se llama polling y tiene dos problemas obvios: gastás llamadas para escuchar "no pasó nada", y te enterás tarde.

Un webhook invierte la dirección. Vos registrás una dirección tuya, y cuando pasa algo, el otro servicio te manda una petición HTTP.

Es lo mismo que dejar tu teléfono en vez de llamar cada media hora para preguntar si hay novedades.

Cómo se ve en concreto

Registrás una URL. Cuando ocurre el evento, llega algo así:

POST /webhooks/pagos HTTP/1.1 X-Signature: sha256=8f3a... Content-Type: application/json

{"evento":"pago.aprobado","id":"pay_123","monto":4500}

Tu servidor recibe eso, comprueba que sea legítimo, hace lo que corresponda y responde 200.

Verificar la firma no es opcional

Esa dirección es pública: cualquiera que la conozca puede mandarle datos. Sin verificación, cualquiera podría decirle a tu sistema "este pago fue aprobado".

Por eso los servicios serios firman cada envío con un secreto compartido. Tu trabajo es recalcular esa firma sobre el cuerpo recibido y compararla.

Tres detalles que se pasan por alto:

• Hay que firmar sobre el cuerpo crudo, no sobre el JSON ya parseado y vuelto a serializar. Un espacio de diferencia y la firma no coincide.
• La comparación debe ser de tiempo constante, no un simple igual, para no filtrar información por el tiempo de respuesta.
• Muchos servicios incluyen una marca de tiempo: conviene rechazar envíos viejos, para que nadie pueda reenviar uno capturado.

Los tres detalles que rompen integraciones

1. Responder rápido. El que envía espera unos segundos y, si no contestás, considera que falló y reintenta. Si tu manejador tarda treinta segundos procesando, vas a recibir el mismo evento varias veces.

La forma correcta: validar, guardar el evento en una cola, responder 200, y procesar después. El webhook confirma la recepción, no el trabajo.

2. Los eventos se repiten. Por reintentos, por fallas de red, por reenvíos manuales. Tu manejador tiene que ser idempotente: recibir dos veces "pago aprobado" no puede cobrar dos veces.

La forma habitual es guardar el identificador del evento y descartar los repetidos.

3. El orden no está garantizado. Podés recibir "pedido actualizado" antes que "pedido creado". Si tu lógica asume secuencia, va a fallar de formas raras e intermitentes. Cuando el orden importa, hay que apoyarse en marcas de tiempo o en el estado actual, no en el orden de llegada.

Cómo se prueban

El problema clásico: el servicio necesita una dirección pública y vos estás desarrollando en tu máquina.

Dos caminos: un túnel que publique tu puerto local temporalmente, o guardar los eventos que llegan a un entorno de pruebas y reproducirlos localmente. El segundo es más aburrido y mucho más confiable para depurar.

Y el consejo que más tiempo ahorra: casi todos los servicios guardan el historial de entregas con el cuerpo enviado, el código de respuesta y la respuesta. Antes de tocar código, mirá ese historial. La mitad de las veces el problema está ahí a la vista: un 404 por una ruta mal escrita, o un 500 que dice exactamente qué falló.

Dónde aparecen

Casi en todos lados: GitHub cuando hacés push, las plataformas de pago cuando se aprueba un cobro, WhatsApp cuando llega un mensaje, los formularios cuando alguien los envía.

En ArduMaker es el mecanismo que dispara los despliegues: GitHub avisa, el servidor valida la firma y ejecuta la construcción.