Cómo utilizar webhooks en n8n: prueba, producción y seguridad
Un webhook permite que otro sistema inicie un workflow enviando una petición HTTP. Es una de las formas más flexibles de conectar formularios, aplicaciones y servicios externos con n8n.
Resumen rápido
- n8n muestra una URL de prueba y otra de producción.
- La URL de prueba funciona mientras el editor escucha el evento.
- La URL de producción requiere publicar el workflow.
- Los datos recibidos pueden incluir cuerpo, cabeceras y parámetros.
- Un webhook público necesita autenticación, validación y límites.
Qué es un webhook
Un webhook es un endpoint HTTP que espera una solicitud. Cuando recibe una petición válida, entrega los datos al workflow y provoca su ejecución. A diferencia de una consulta periódica, el evento llega cuando ocurre.
Puede recibir métodos como GET o POST, dependiendo de la configuración. Para formularios y eventos estructurados, POST suele ser la opción más habitual.
URL de prueba frente a URL de producción
El nodo Webhook de n8n proporciona dos direcciones. La URL de prueba está pensada para construir el workflow y permite visualizar inmediatamente los datos recibidos en el editor. Debes pulsar Listen for test event antes de enviar la solicitud.
La URL de producción se utiliza cuando el workflow está publicado. No sustituyas una por otra en una integración externa: sus rutas y comportamiento son diferentes.
| Uso | URL de prueba | URL de producción |
|---|---|---|
| Objetivo | Desarrollo y diagnóstico | Servicio real |
| Disponibilidad | Mientras escucha el editor | Con el workflow publicado |
| Datos visibles | Directamente en el lienzo | En la ejecución registrada |
Enviar una petición de prueba
Crea un workflow, añade Webhook, selecciona POST y copia la URL de prueba. Después activa la escucha y envía un JSON desde otra terminal.
No utilices información real en las primeras pruebas. Un ejemplo ficticio permite revisar la estructura sin almacenar datos personales.
curl -X POST 'https://n8n.tudominio.com/webhook-test/tu-ruta'
-H 'Content-Type: application/json'
-d '{"nombre":"Ejemplo","email":"[email protected]"}'Validar la información recibida
Nunca presupongas que un webhook recibirá todos los campos ni que tendrán el tipo correcto. Comprueba campos obligatorios, longitud, formato y valores permitidos antes de guardar o reenviar información.
Cuando la validación falla, responde con un código adecuado y no continúes hacia nodos que envían correos, crean registros o ejecutan acciones con coste.
Proteger un webhook público
Una URL difícil de adivinar no sustituye a la autenticación. Cuando el servicio emisor lo permita, utiliza credenciales del webhook, firmas o un secreto compartido y verifica el origen del evento.
También debes considerar límites de frecuencia, tamaño máximo, repetición de eventos e idempotencia. Algunos proveedores reintentan una petición si no reciben respuesta; sin control de duplicados podrías procesar dos veces el mismo pago o mensaje.
- Utiliza HTTPS.
- Habilita autenticación o validación de firma.
- Rechaza cuerpos demasiado grandes o inesperados.
- Registra un identificador del evento para evitar duplicados.
- No devuelvas secretos ni trazas internas en la respuesta.
- Aplica límites en Cloudflare o en el proxy cuando sea apropiado.
Webhooks detrás de Caddy o Cloudflare
Cuando n8n se ejecuta detrás de un proxy inverso, configura correctamente la URL pública de los webhooks. Si n8n genera direcciones internas o HTTP, revisa WEBHOOK_URL, el dominio, el protocolo y el número de proxies de confianza.
Prueba siempre la URL de producción desde una red externa. Una llamada que funciona desde el propio VPS no demuestra que DNS, Cloudflare y HTTPS estén configurados correctamente.
Fuentes oficiales
Continúa aprendiendo
Consulta la guía introductoria de BreachReel o descubre la formación estructurada para avanzar desde los fundamentos hasta automatizaciones completas.