Clase 05 · Módulo 05
Webhooks: recibir eventos en n8n
Webhooks: recibir eventos en n8n
Qué logras en esta clase
Haces que un flujo arranque en el momento en que otro sistema le avisa, y controlas quién puede avisarle.
- Distingues la dirección de prueba de la de producción.
- Decides qué responde tu flujo y cuándo.
- Proteges el webhook con autenticación.
02
Preguntar o que te avisen
Hasta aquí tu flujo iba a buscar los datos. Con un webhook, los datos llegan solos en el instante en que algo ocurre.
03
Qué es un webhook
Es una dirección web propia de tu flujo. Cuando otro sistema le envía una petición HTTP, el flujo se ejecuta con los datos que venían en ella.
Es una API al revés: en las clases anteriores tú llamabas; ahora te llaman a ti. Todo lo que aprendiste de métodos, cabeceras y cuerpo sigue valiendo, visto desde el otro lado.
04
Webhook o consulta por horario
| Consulta por horario | Webhook | |
|---|---|---|
| Quién inicia | Tu flujo | El otro servicio |
| Demora | Hasta el próximo ciclo | Inmediata |
| Llamadas | Muchas, casi todas vacías | Solo cuando pasa algo |
| Requisito | Que exista API | Que el servicio envíe webhooks y tu n8n sea alcanzable |
Si el servicio ofrece webhooks, suele ser la mejor opción. Si no, queda consultar cada cierto tiempo.
05
El recorrido de un evento
Tú registras la dirección de tu webhook una vez, en el panel del otro servicio, y eliges qué eventos quieres recibir. Desde ahí, cada evento es una petición.
06
Los campos del nodo Webhook
| Campo | Qué define |
|---|---|
| HTTP Method | Qué método acepta: GET, POST, PUT, PATCH, DELETE o HEAD |
| Path | El final de la dirección |
| Authentication | Cómo comprueba quién llama |
| Respond | Cuándo y qué contesta |
El servicio que te llama define el método; casi siempre es POST. Si llega una petición con otro método, el nodo no la acepta.
07
Dos direcciones por nodo
| Test URL | Production URL | |
|---|---|---|
| Cuándo escucha | Mientras pruebas en el editor | Con el flujo publicado |
| Dónde ves los datos | En el editor | En Executions |
| Para qué | Construir | Operar |
Ambas aparecen arriba en el panel del nodo; al pulsar cada etiqueta cambia la dirección mostrada. Se diferencian en una parte de la ruta.
08
Probar un webhook
- Abre el nodo Webhook y deja visible la Test URL.
- Pulsa Listen for Test Event. El nodo queda esperando.
- Envía una petición a esa dirección desde el servicio, o desde otro flujo con un HTTP Request.
- Los datos recibidos aparecen en el panel de salida.
La escucha de prueba se activa a pedido. Si nadie pulsó el botón, la Test URL no responde.
09
El error número uno
En el servicio externo va siempre la Production URL, y solo responde cuando el flujo está publicado (módulo 2, clase 5). Un borrador guardado no recibe nada por esa dirección.
10
Test para construir, Production para operar
Cuando un webhook «no llega», la primera pregunta es a cuál de las dos direcciones le están enviando.
11
Qué recibe el flujo
El nodo entrega un ítem con la petición separada en partes:
| Campo | Contiene |
|---|---|
body | El cuerpo: los datos del evento |
headers | Las cabeceras |
query | Los parámetros de consulta |
params | Los parámetros de la ruta |
En una expresión, el correo que venía en el cuerpo se lee como {{ $json.body.correo }}.
12
La ruta
Por defecto el Path es un texto aleatorio, lo que evita choques entre webhooks. Puedes cambiarlo por uno legible y agregar partes variables con dos puntos:
pedidos/:sucursalUna llamada a .../pedidos/centro deja centro disponible en params.sucursal.
13
Cuándo responde el flujo
El campo Respond tiene cuatro valores:
| Valor | Qué contesta |
|---|---|
| Immediately | Código de éxito y un mensaje fijo, apenas recibe |
| When Last Node Finishes | La salida del último nodo, al terminar |
| Using 'Respond to Webhook' Node | Lo que tú definas, donde tú definas |
| Streaming response | Datos a medida que avanza; requiere nodos que lo admitan |
Con Response Code eliges el código que se devuelve cuando todo sale bien.
14
Cuál elegir
- El que llama solo avisa (un pago, un formulario): Immediately. Muchos servicios esperan pocos segundos y, si no contestas, reenvían el evento.
- El que llama necesita un dato de vuelta (una consulta de stock): When Last Node Finishes o el nodo de respuesta.
- Quieres controlar código y cuerpo: el nodo Respond to Webhook.
15
El nodo Respond to Webhook
- En el nodo Webhook, pon Respond en Using 'Respond to Webhook' Node.
- Agrega el nodo Respond to Webhook en el punto del flujo donde ya tienes lo que quieres contestar.
- En Respond With elige el contenido: JSON, Text, First Incoming Item, All Incoming Items o No Data, entre otros.
- En las opciones, ajusta Response Code si hace falta.
Los nodos siguientes igual se ejecutan; quien llamó ya tiene su respuesta.
16
Lo que conviene saber del nodo de respuesta
- Si hay varios, solo responde el primero que se ejecuta.
- Si el flujo termina sin pasar por ninguno, se envía una respuesta estándar con código 200.
- Si el flujo falla antes de llegar a él, quien llama recibe un 500.
- Con varios ítems de entrada usa solo el primero, salvo que elijas All Incoming Items.
17
Responder distinto según el caso
18
Una dirección pública es una puerta abierta
Cualquiera que conozca la dirección puede ejecutar tu flujo. Sin autenticación, un webhook confía en todo el mundo.
19
Las opciones de Authentication
| Opción | Cómo comprueba |
|---|---|
| None | No comprueba |
| Basic Auth | Usuario y contraseña |
| Header Auth | Una cabecera con un valor secreto |
| JWT Auth | Un token firmado |
| n8n User Auth | Solo usuarios con sesión en tu n8n |
La elección depende de qué sabe enviar el servicio que te llama. Header Auth es la más compatible: casi todos permiten agregar una cabecera propia.
20
Proteger con Header Auth
- En Authentication elige Header Auth.
- Crea la credencial: en Name el nombre de la cabecera, en Value un texto largo y aleatorio.
- En el servicio que te llama, configura esa misma cabecera con ese mismo valor.
- Prueba dos veces: con la cabecera y sin ella. Sin ella, el flujo no debe ejecutarse.
El secreto queda en una credencial de n8n, como toda clave (clase 3).
21
Otras defensas del nodo
En Options hay ajustes que suman protección:
- IP(s) Allowlist: solo acepta llamadas desde las direcciones IP que indiques; las demás reciben 403. Útil si el servicio publica las suyas.
- Ignore Bots: descarta visitas de rastreadores y vistas previas de enlaces.
- Allowed Origins (CORS): limita desde qué sitios web puede llamarse en un navegador; por defecto acepta todos.
Y una defensa que no es del nodo: valida los datos que llegan antes de usarlos.
22
Límites que debes conocer
- Tamaño: una petición puede pesar hasta 16 MB. En una instalación propia se cambia con la variable
N8N_PAYLOAD_SIZE_MAX. - Alcance: un n8n en
localhostno es visible desde internet. Ningún servicio externo puede llamarlo hasta que lo expongas (clase 6). - Repeticiones: muchos servicios reenvían un evento si no recibieron respuesta. Tu flujo debe tolerar el mismo evento dos veces (módulo 7, clase 5).
23
Archivos por webhook
Para recibir un archivo, agrega en Options la opción Binary Property y escribe el nombre del campo donde quedará. Funciona con POST, PUT y PATCH.
El archivo llega como dato binario y se trabaja como en el módulo 3, clase 6. Para recibir el cuerpo tal cual, sin que n8n lo interprete, existe la opción Raw Body.
24
Errores comunes
- Entregar la Test URL al servicio externo.
- Olvidar publicar el flujo y esperar eventos en la Production URL.
- Dejar Authentication en None «porque la ruta es larga».
- Tardar un minuto en responder y recibir el mismo evento tres veces.
- Leer
$json.correocuando el dato estaba en$json.body.correo.
25
Lo que te llevas
- Un webhook es una dirección que ejecuta tu flujo cuando alguien la llama.
- Test URL para construir; Production URL, con el flujo publicado, para operar.
- La petición llega separada en
body,headers,queryyparams. - Respond define cuándo contestas; el nodo Respond to Webhook, qué.
- Todo webhook real lleva autenticación.
26
Hazlo ahora
En 15 minutos, con dos flujos en tu n8n:
- Flujo A: un Webhook con método POST y un Respond to Webhook que devuelva un JSON con un saludo.
- Protégelo con Header Auth y publícalo.
- Flujo B: Manual Trigger y un HTTP Request con POST a la Production URL de A, con la misma cabecera en una credencial.
- Ejecuta B y mira la ejecución de A en Executions.
- Quita la credencial en B y ejecuta de nuevo.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026