- Nada instalado ni ninguna cuenta: la prueba de esta guía funciona con lo que ya tienes
- Una terminal — más abajo se explica cómo abrirla
Introducción
Un webhook es un aviso automático que un servicio envía a una dirección web tuya cuando pasa algo. Técnicamente es una petición HTTP —el mismo mecanismo con el que tu navegador pide una página—, casi siempre del tipo POST, que es el que se usa para enviar datos en vez de pedirlos.
En lugar de que tú preguntes “¿ha pasado algo?” una y otra vez (eso se llama polling), el servicio te avisa cuando toca.
En una frase: ocurre algo → el servicio envía una petición a tu dirección → tu sistema reacciona.
Una analogía: el polling es llamar a la panadería cada diez minutos para ver si ya hay pan. El webhook es dejarles tu teléfono para que te llamen cuando salga del horno.
Problema que resuelve
Sin webhooks, tu sistema tendría que preguntarle al servicio cada pocos minutos si hay novedades. Eso llega tarde y, como muchos servicios limitan cuántas preguntas puedes hacer al día, además gasta ese cupo para nada. Con un webhook, quien genera el evento —donde alojas tu código (GitHub, GitLab…), tu pasarela de pagos, tu gestor de clientes— te avisa en el momento.
Sirve cuando quieres reaccionar pronto —una tarea automática que falla, un cobro rechazado, un formulario enviado— y el servicio de origen ya sabe emitir estos avisos. Casi todos los grandes lo hacen; búscalo en su panel como «Webhooks» o «Notificaciones».
Cómo funciona
- Ocurre un evento
- El emisor arma un POST
- Tu URL recibe el JSON
- Tu código decide qué hacer
- Configuras en el emisor una dirección tuya que reciba el aviso (la verás como “webhook URL” o “URL de callback”).
- Cuando pasa el evento, el emisor envía un POST con un cuerpo —casi siempre en formato JSON— y algunas cabeceras.
- Tu receptor contesta con un código 200 para decir “recibido”. Los códigos que empiezan por 2 significan que fue bien; por eso se escribe 2xx.
- Si tu lado falla (códigos que empiezan por 5, o tarda demasiado), muchos emisores lo reintentan: puedes recibir el mismo aviso más de una vez.
Anatomía de una petición
| Parte | Ejemplo | Para qué |
|---|---|---|
| Método | POST | Enviar el evento |
| URL | la que configuraste | Destino |
| Cabecera | Content-Type: application/json | Cómo interpretar el cuerpo |
| Cuerpo | { "event": "…" } | Datos del evento |
Ejemplo de cuerpo mínimo (inventado para la guía):
{
"event": "demo.ping",
"source": "guide",
"deliveredAt": "2026-07-16T10:00:00Z"
}Pruébalo ahora (sin montar nada)
El comando de abajo hace POST a postman-echo.com (se abre en una pestaña nueva), un servicio público que te devuelve tal cual lo que le mandes. Con eso ves el gesto entero sin tener servidor.
Elige tu sistema en las pestañas: el comando cambia entre Windows y el resto.
curl -sS -X POST "https://postman-echo.com/post" \
-H "Content-Type: application/json" \
-H "X-Demo-Event: demo.ping" \
-d "{\"event\":\"demo.ping\",\"source\":\"guide\",\"deliveredAt\":\"2026-07-16T10:00:00Z\"}"En la respuesta busca la propiedad json (o el campo equivalente): debería coincidir con el cuerpo. Status esperado: 200.
Si el eco público falla (timeout o 5xx), abre webhook.site (se abre en una pestaña nueva), copia la URL única que te da y úsala en lugar de https://postman-echo.com/post.
Cuando montes un emisor real, la URL será tuya (un endpoint HTTPS) o, a veces, la URL de un Incoming Webhook de un chat. Hoy solo importa el gesto: evento → POST → alguien lo recibe.
Seguridad (lo mínimo antes de producción)
Cuando pases de la prueba a algo real:
- Usa HTTPS, no
http://. Si no, el aviso viaja sin cifrar. - Si el emisor ofrece firma, verifícala. Firmar significa que el emisor añade un código calculado con un secreto que solo compartís vosotros dos; comprobarlo demuestra que el aviso viene de él y no de alguien que adivinó tu dirección. Cada proveedor documenta cómo hacerlo.
- Los emisores reintentan, así que puedes recibir el mismo aviso dos veces. Si eso te importa, guarda el identificador de cada entrega y descarta los repetidos.
- Contesta pronto con un 200 y haz después el trabajo lento (mandar el aviso, escribir en tu base de datos). Si tardas en contestar, el emisor cree que has fallado y reintenta.
Para el detalle de HTTP: MDN — HTTP (se abre en una pestaña nueva). Para el formato concreto de cada aviso, la documentación del emisor (GitHub, Stripe, etc.).
Errores habituales
| Síntoma | Causa probable | Qué mirar |
|---|---|---|
| El emisor reintenta sin parar | Tu dirección dio error o tardó demasiado | El registro de tu receptor; contesta 200 antes de ponerte a trabajar |
| 404 en el webhook | URL mal copiada o recurso borrado | Regenera o corrige la URL |
| 401 / firma inválida | Secreto distinto en emisor y receptor | Alinea el secreto |
| Destino de chat spameado | URL de Incoming Webhook filtrada | Revoca esa URL y crea otra |
Cuándo usar otra alternativa
- Polling
- Si no hay webhooks o el volumen es bajísimo y aceptas retraso.
- Email / UI nativa del proveedor
- Si no necesitas automatizar todavía.
- Cola o bus de eventos
- Si ya tienes infra interna y el SaaS solo es una fuente más.
Siguiente paso
Con el modelo mental claro, elige un camino según lo que necesites:
- Un emisor concreto — registra tu dirección en su panel, verifica la firma y contesta 200 (pagos, integración continua, formularios…).
- Avisar a personas — desde tu receptor, llama a la API de tu chat o a su Incoming Webhook.
- Profundizar — si el HTTP de base todavía se te resiste, MDN (se abre en una pestaña nueva) lo explica desde cero. Si vas a cobros, el siguiente concepto es el evento firmado de la pasarela de pagos.
Con eso ya puedes montar el patrón en tu propio stack.
Automatizaciones guiadas
Aplica lo aprendido en la guía con una de nuestras automatizaciones: