HookSteadBETA

¿Qué es un webhook? Explicación sencilla con ejemplos

Qué es un webhook, cómo funciona, en qué se diferencia de una API y qué hay que tener en cuenta para recibirlos de forma segura y fiable.

5 min de lectura · Actualizado · English · Português

La respuesta corta

Un webhook es una petición HTTP que un sistema envía a otro cuando ocurre algo. En lugar de que tu aplicación pregunte a Stripe cada pocos segundos "¿ya ha pagado alguien?", Stripe llama a una URL que tú le diste en el momento en que se completa el pago.

Esa URL es tu endpoint de webhook. El cuerpo de la petición describe el evento, normalmente en JSON, y las cabeceras llevan datos adicionales, como una firma que demuestra quién lo envió.

Un ejemplo

Así se ve un webhook típico, recortado:

POST /webhooks/stripe HTTP/1.1
Host: api.tuapp.com
Content-Type: application/json
Stripe-Signature: t=1793952000,v1=5257a869e7ec…

{"id":"evt_1Q…","type":"invoice.paid","data":{"object":{…}}}

Tu endpoint hace tres cosas: comprueba la firma, guarda el evento y responde rápido con un 2xx. Cualquier otra respuesta (un 5xx, un tiempo de espera agotado, una conexión cortada) le dice al remitente que la entrega falló, y la mayoría lo vuelve a intentar más tarde.

¿Para qué sirve un webhook?

Para enterarte de lo que pasa en otros sistemas en cuanto pasa:

  • Pagos: Stripe o PayPal te avisan de un cobro, un reembolso o una suscripción cancelada.
  • Código: GitHub te avisa de un push o de una pull request, y arranca tu CI.
  • Tiendas: Shopify te avisa de un pedido nuevo.
  • Mensajería: un webhook de Discord o de Slack publica un mensaje en un canal.
  • Automatización: n8n o Zapier inician un flujo cuando llega una petición.

Webhook vs. API

Con una API, tú preguntas cuando quieres: "dame la factura 42". Con un webhook, el otro sistema te avisa cuando ocurre algo: "la factura 42 se acaba de pagar". Dicho de otro modo: con una API llamas tú; con un webhook te llaman a ti.

APIWebhook
Quién inicia la peticiónTúEl proveedor
CuándoCuando tú decidesCuando ocurre un evento
Si no pasa nadaSigues gastando peticionesNo se envía nada
Quién aloja el endpointEl proveedorTú

Las integraciones sólidas usan ambos: el webhook avisa de que algo cambió y la API devuelve el estado actual. Más detalles (en inglés) en webhook vs. API.

Qué puede salir mal

Los webhooks son fáciles de empezar y fáciles de hacer mal:

  • Tu endpoint está caído durante un despliegue y el proveedor se rinde tras sus reintentos.
  • Alguien falsifica una petición a tu URL pública porque no se comprueba la firma. Ver firmas HMAC (en inglés).
  • El mismo evento llega dos veces y tu aplicación cobra, envía o entrega dos veces. Ver reintentos e idempotencia (en inglés).
  • Nadie sabe qué pasó, porque ni la petición ni la respuesta quedaron registradas.

Dónde encaja HookStead

HookStead da a cada proveedor una URL estable, verifica su firma al llegar, guarda cada evento antes de responder y lo reenvía a tu aplicación con reintentos, su propia firma y un registro completo de cada intento. Si algo falla, lo ves, arreglas tu endpoint y lo vuelves a enviar. El plan gratuito incluye 10.000 eventos al mes; consulta la documentación (en inglés).

Preguntas frecuentes

¿Qué es un webhook en palabras sencillas?
Es un aviso automático: cuando pasa algo en un sistema (un pago, un pedido, un push), ese sistema envía una petición HTTP a una URL tuya con los datos del evento.
¿Cuál es la diferencia entre un webhook y una API?
Con una API eres tú quien pide los datos cuando quiere. Con un webhook es el otro sistema quien te los envía cuando ocurre un evento.
¿Qué es una URL de webhook?
Es la dirección a la que el remitente envía sus webhooks. Debe ser pública, usar HTTPS y responder rápido con un código 2xx.