Cómo usar un Webhook en n8n paso a paso

Un webhook convierte tu workflow de n8n en un endpoint: una aplicación externa le envía una petición HTTP y eso lanza la ejecución. En este tutorial creas un webhook real, lo pruebas con curl, inspeccionas los datos que llegan y le das una respuesta. No hace falta ningún servicio externo: solo tu instancia de n8n y un terminal.

Qué es un webhook

Un webhook es una URL que n8n mantiene escuchando llamadas HTTP. Cuando otra aplicación hace una petición a esa URL, se dispara el workflow. En esquema:

Aplicación externa → Webhook de n8n → Workflow

La aplicación externa puede ser cualquier cosa capaz de hacer una petición HTTP: un script, otra herramienta, un formulario o el propio curl de tu máquina.

Requisitos previos

Una instancia de n8n funcionando. Si no la tienes, sigue primero cómo instalar n8n con Docker.
Conocimientos básicos de workflows. En el tutorial anterior construiste tu primer flujo y conoces los nodos y las conexiones; puedes repasarlo en cómo crear tu primer workflow en n8n.

No vamos a repetir esas guías: aquí el disparador deja de ser manual y pasa a ser una llamada HTTP.

Crear un nuevo workflow

Crea un workflow nuevo y añade el nodo Webhook como primer nodo. Es el nodo que espera la petición externa y arranca el workflow cuando llega.

Configurar el Webhook

Abre el nodo Webhook y configura dos campos básicos:

HTTP Method: POST. Indica que el workflow espera peticiones que envían datos en el cuerpo (body).
Path: mi-primer-webhook. Es el identificador del endpoint dentro de tu instancia.

Opciones como autenticación, CORS o rate limiting no las necesitas ahora; se tratan más adelante.

URL de prueba y URL de producción

El nodo Webhook tiene dos URLs. En la parte superior del panel del nodo puedes alternar entre ellas con Test URL y Production URL:

La Test URL se usa mientras el workflow está en modo de prueba. Permite ver en el editor los datos de cada ejecución, lo que resulta cómodo para depurar.
La Production URL se usa cuando el workflow está publicado y activo. Sirve peticiones reales, pero no muestra los datos en el editor: las ejecuciones de producción se revisan en la pestaña Executions del workflow.

Ambas comparten la dirección de tu instancia y solo cambian el prefijo. En una instalación local son parecidas a esto (ejemplos, no URLs reales):

http://tu-dominio.example/webhook-test/mi-primer-webhook

http://tu-dominio.example/webhook/mi-primer-webhook

El prefijo /webhook-test/ corresponde a la versión de prueba y /webhook/ a la de producción. En tu instalación, n8n te muestra las URLs exactas directamente en el panel del nodo: cópialas de ahí en lugar de reconstruirlas a mano.

Poner el webhook en modo escucha

Para probar, tienes que registrarlo de forma temporal. En el nodo Webhook usa la acción Listen for test event (en español, escuchar evento de prueba). El webhook de prueba queda escuchando unos 120 segundos, tiempo suficiente para enviar la petición desde el terminal.

Si no lo pones en modo escucha y no está publicado, la llamada a la Test URL no arranca nada.

Enviar una petición de prueba

Desde el terminal, envía una petición a la Test URL con curl:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Mateo","servicio":"Automatización"}' \
  URL_DEL_WEBHOOK

Sustituye URL_DEL_WEBHOOK por la Test URL que te muestra n8n. Qué hace cada parte:

-X POST: indica el método HTTP de la petición, en este caso POST.
-H "Content-Type: application/json": declara que el cuerpo de la petición viaja como JSON, para que n8n lo interprete como tal.
-d '{"nombre":"Mateo","servicio":"Automatización"}': es el cuerpo (data) que se envía, en este caso un JSON con dos campos.

Si todo va bien, n8n recibe la petición y ejecuta el nodo Webhook. Verás la ejecución reflejada en el editor.

Ver los datos recibidos

Selecciona el nodo Webhook y abre su output. n8n no expone el cuerpo de la petición directamente en la raíz: envuelve la petición en una estructura que incluye headers, query, params y body. Lo que envíes con -d estará dentro de body:

{
  "headers": { "...": "..." },
  "query": {},
  "params": {},
  "body": {
    "nombre": "Mateo",
    "servicio": "Automatización"
  }
}

De este modo, los campos que mandaste con curl se leen a través de body. Es la estructura actual del nodo Webhook y conviene acostumbrarse a ella antes de conectar servicios reales.

Usar los datos del webhook

Añade un nodo Edit Fields después del Webhook para trabajar con los datos recibidos. Vas a quedarte con el nombre y el servicio, y añadir un campo nuevo.

En Fields to Set, añade tres campos. Para los dos primeros necesitas usar el valor dinámico del webhook mediante una expresión; n8n usa la sintaxis {{ $json... }} para referirse a los datos de la entrada:

nombre = {{ $json.body.nombre }}
servicio = {{ $json.body.servicio }}
estado = recibido

Al ejecutar de nuevo, la entrada del Edit Fields es lo que entregó el Webhook, y su salida queda así:

{
  "nombre": "Mateo",
  "servicio": "Automatización",
  "estado": "recibido"
}

Si las expresiones no devuelven nada, comprueba el nombre exacto del campo dentro de body: un body.nombre no coincide si el dato real está en otro campo.

Responder a la petición

Con un webhook, no solo recibes: también puedes devolver una respuesta HTTP al emisor. El mecanismo actual de n8n para controlarla es el nodo Respond to Webhook:

En el nodo Webhook, en el campo Respond, elige Using ‘Respond to Webhook’ Node. Sin esto, el Webhook responde por sí solo y el nodo de respuesta se ignora.
Añade el nodo Respond to Webhook al final del workflow, conectado después del Edit Fields.
En Respond With, elige JSON y escribe un cuerpo de respuesta, por ejemplo:

{
  "ok": true,
  "mensaje": "Datos recibidos correctamente"
}

Con esto, quien hizo la petición recibe ese JSON como cuerpo de la respuesta HTTP, en lugar del resultado del workflow. Envuelve de nuevo la petición con curl desde el terminal y verás la respuesta impresa al final.

Activar el workflow

La Test URL solo funciona mientras estás con el nodo en modo escucha de prueba. Para que el webhook funcione de forma permanente y dé servicio a la Production URL, el workflow tiene que estar activo (publicado): actívalo desde el editor con el interruptor correspondiente.

Mientras está activo, n8n registra el webhook de producción y responde a las llamadas a la Production URL sin que abras el editor. A diferencia del modo de prueba, ya no ves los datos en el lienzo: las ejecuciones se consultan en la pestaña Executions del workflow.

Activar el workflow no elimina el modo de prueba: mientras lo estás editando sigues pudiendo usar la Test URL con Escuchar evento de prueba.

Probar la URL de producción

Con el workflow activo, repite la petición usando ahora la Production URL:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Mateo","servicio":"Automatización"}' \
  URL_DEL_WEBHOOK

Comprueba que recibes la respuesta configurada (el { "ok": true, ... } de Respond to Webhook). Después abre el workflow en el editor y revisa la pestaña Executions para ver la ejecución recién creada y las expresiones evaluadas.

GET vs POST

Los dos métodos más habituales en webhooks:

GET: se usa normalmente para consultar o pasar parámetros simples. En n8n conviene reservarlo para casos donde no se envíe un cuerpo, como comprobar que un endpoint responde.
POST: se usa para enviar información en el body (JSON, formularios, etc.). Es el método típico de los webhooks de eventos y el que usas en este tutorial.

La elección depende de lo que haga el emisor; n8n te deja configurar el método en el nodo Webhook. Con el campo en POST, rejects automáticamente las peticiones que no usen ese método.

Path y endpoints

El Path es la parte de la URL que identifica a este webhook dentro de tu instancia. En este tutorial es mi-primer-webhook, y n8n lo coloca al final de la ruta:

http://tu-dominio.example/webhook/mi-primer-webhook

Elige paths descriptivos y difícilmente adivinables. Algo como mi-primer-webhook sirve para aprender, pero un path fácil de predecir aumenta el riesgo de que cualquiera encuentre tu endpoint; para producción conviene paths más específicos y, sobre todo, la protección que se comenta a continuación.

Seguridad básica

Un webhook público recibe peticiones de cualquiera que conozca la URL. Antes de exponerlo a tráfico real conviene valorar:

Autenticación y tokens en la llamada.
Headers secretos conocidos solo por el emisor.
Validación de los datos recibidos antes de tratarlos como fiables.
HTTPS para que la información viaje cifrada.
Rate limiting o controles equivalentes cuando se prevea tráfico externo.

Este tutorial no implementa autenticación: dejar eso para un tutorial específico evita dar una falsa sensación de seguridad con una configuración a medias.

Errores frecuentes

Enviar a la Test URL sin estar en modo escucha: si el webhook no está a la escucha, la llamada no dispara nada. Usa Listen for test event antes de lanzar el curl.
Usar la Production URL con el workflow desactivado: sin workflow activo no hay webhook de producción registrado, y la llamada falla.
Método HTTP incorrecto: si configuraste POST y envías un GET (o al revés), la petición no llega al workflow.
Path incorrecto: la URL debe terminar exactamente en el path que configuraste. Un typo en el path apunta a un endpoint inexistente.
JSON mal formado: un -d con comillas desbalanceadas o una coma mal puesta hace que n8n no pueda interpretar el body.
Olvidar Content-Type: application/json: sin él, n8n puede no tratar el cuerpo como JSON y body queda vacío o como texto.
Acceder al campo equivocado en expresiones: recuerda que los datos están dentro de body ({{ $json.body.nombre }}), no en la raíz del item.
El webhook no responde nada: además de revisar el estado del workflow, comprueba que la instancia de n8n está en marcha con los logs del contenedor.

Qué aprender después

Tener un endpoint que responde a peticiones HTTP es la base de muchas automatizaciones. Los siguientes pasos naturales son:

HTTP Request: para que un workflow, además de recibir, llame a otras APIs.
Autenticación de los webhooks para no dejar endpoints abiertos.
APIs REST: para diseñar endpoints con rutas y métodos coherentes.
Validación de datos: para rechazar peticiones incompletas o incorrectas.
Conectar el webhook con una base de datos para guardar lo recibido.

Conclusión

Ya tienes un webhook funcional en n8n: configurado, probado con curl, con los datos inspeccionados y transformados, con una respuesta controlada por Respond to Webhook y con su versión de producción activa.

El siguiente tutorial natural es Cómo usar el nodo HTTP Request en n8n: ahí verás la otra dirección del HTTP, cuando es tu workflow el que sale a pedir datos a un servicio externo.