Webhook en n8n paso a paso: recibir, validar y responder

Un webhook evita consultar constantemente si ocurrió algo: el sistema origen avisa a n8n. Esa comodidad convierte la URL en una frontera pública que hay que proteger.

Respuesta rápida

Crea un nodo Webhook, elige método y ruta, configura autenticación, recibe un evento de prueba, valida estructura y firma, controla duplicados y responde con Respond to Webhook. No actives escrituras irreversibles hasta probar eventos repetidos y entradas inválidas.

La idea clave: un webhook no es "una URL para que entren cosas". Es un contrato entre dos sistemas. Si ese contrato no define quién llama, qué envía, cómo se autentica, qué respuesta espera y qué ocurre si se repite, el workflow está incompleto aunque funcione una vez en el editor.

Para una empresa de Madrid que quiere automatizar leads, facturas, WhatsApp, reservas o avisos internos, los webhooks son una pieza central. También son una de las formas más rápidas de romper algo si se publican sin control.

Qué es un webhook en n8n

Un webhook es un endpoint HTTP que n8n expone para recibir peticiones externas. Un formulario, una tienda online, Stripe, Shopify, Meta, un CRM o una app propia pueden enviar un evento a esa URL cuando ocurre algo: lead creado, pedido pagado, factura emitida, mensaje recibido o tarea actualizada.

La documentación oficial del Webhook node de n8n describe sus modos, URLs de prueba y producción, métodos HTTP, autenticación y opciones de respuesta. Esa es la referencia que conviene revisar antes de copiar una URL en un sistema externo.

La diferencia con consultar una API cada minuto es importante:

Para procesos con respuesta rápida, el webhook suele ser mejor. Para procesos donde el origen no puede avisar, toca usar polling o una tarea programada.

Cuándo usar un webhook

Usa un webhook cuando:

• un formulario debe avisar en el momento;
• un pago confirmado debe activar una tarea;
• un pedido necesita crear una oportunidad;
• WhatsApp o una plataforma externa envía eventos;
• un proveedor puede llamar a una URL tras cada cambio;
• una app propia necesita entregar datos a n8n;
• quieres reducir consultas repetidas a una API.

No uses un webhook si no puedes validar quién llama, si el evento no tiene identificador, si el sistema origen no documenta reintentos o si la acción posterior es irreversible y no tienes control de duplicados.

El mapa mínimo antes de crear el nodo

Antes de abrir n8n, escribe:

Sin este mapa, el webhook funciona como una puerta abierta sin procedimiento.

Paso 1: define el contrato

Documenta quién llama, método, autenticación, content type, body, firma, tiempo máximo de respuesta y política de reintentos. Si el emisor reintenta al no recibir 2xx, tu workflow debe soportar duplicados.

Un contrato mínimo puede verse así:

{
  "event_id": "evt_123",
  "event_type": "lead.created",
  "created_at": "2026-07-30T09:00:00Z",
  "source": "landing-seo-madrid",
  "data": {
    "name": "Cliente de prueba",
    "email": "prueba@example.com",
    "service": "seo"
  }
}

Lo importante no es usar exactamente esos nombres. Lo importante es que el evento tenga identificador, tipo, fecha, origen y datos. Si llega un JSON sin event_id, tendrás que definir otra clave idempotente, por ejemplo la combinación de formulario, email y timestamp redondeado. Es peor que un ID real, pero mejor que no tener nada.

Paso 1.1: decide qué eventos aceptas

No aceptes "cualquier cosa que llegue". Define una lista:

• lead.created;
• payment.succeeded;
• invoice.approved;
• appointment.requested;
• message.received.

Si llega user.deleted o invoice.cancelled y tu workflow no lo contempla, responde con rechazo controlado o deriva a revisión. La lista blanca protege de eventos inesperados y de cambios futuros del proveedor.

Paso 2: crea el Webhook

El nodo ofrece URL de prueba y de producción. Usa la de prueba mientras escuchas desde el editor. La de producción exige workflow activo.

Elige una ruta que no revele clientes ni secretos. Una URL difícil de adivinar no sustituye autenticación.

Según la documentación del nodo Webhook, puedes configurar autenticación Basic, Header, JWT o ninguna. Si el proveedor firma cada petición, valida además la firma con su procedimiento oficial.

URL de prueba

La URL de prueba sirve mientras estás escuchando desde el editor. Es útil para capturar una muestra y ver la estructura real del payload. No la pegues en producción pensando que quedará activa para siempre.

URL de producción

La URL de producción se usa cuando el workflow está activo. Esta es la que se configura en el sistema emisor cuando el contrato ya está probado.

Método HTTP

Para eventos con body, normalmente usarás POST. No uses GET para enviar datos sensibles. Si el proveedor exige otro método, documenta por qué.

Ruta

La ruta debe ser estable, no contener secretos y no exponer información innecesaria. Mejor /webhook/lead-intake-v1 que /webhook/cliente-super-secreto-token.

Paso 2.1: configura respuesta con intención

n8n permite responder desde el Webhook o usar Respond to Webhook. Para flujos serios, suele ser mejor responder deliberadamente después de validar lo mínimo.

Ejemplo de respuesta aceptada:

{
  "ok": true,
  "received": true,
  "event_id": "evt_123"
}

Ejemplo de rechazo:

{
  "ok": false,
  "error": "invalid_event"
}

No devuelvas trazas internas, nombres de tablas, tokens, URLs privadas ni mensajes de error completos. La respuesta es para el emisor, no para depurar tu infraestructura.

Paso 3: captura una muestra segura

Envía un payload anonimizado:

{
  "event_id": "evt_test_001",
  "event": "lead.created",
  "created_at": "2026-07-28T10:00:00Z",
  "data": {
    "name": "Prueba",
    "email": "test@example.com"
  }
}

Inspecciona body, headers y query. No supongas que los datos están en la raíz.

Guarda una muestra anonimizando cualquier dato personal. Esa muestra te servirá para pruebas posteriores. Si el proveedor manda cabeceras de firma, conserva el formato, pero nunca pegues secretos en documentación pública.

Paso 3.1: entiende dónde llega cada cosa

En un webhook puedes recibir:

• body: datos principales;
• headers: autenticación, firma, content type;
• query: parámetros de URL;
• params: partes dinámicas de ruta;
• metadata de ejecución.

Muchos errores vienen de buscar email en $json.email cuando realmente llega en $json.body.data.email. Antes de escribir expresiones, mira el output real del nodo.

Paso 4: valida antes de actuar

Comprueba:

• método y content type;
• autenticación o firma;
• tipo de evento permitido;
• campos obligatorios;
• tamaño y formato;
• fecha razonable;
• event_id no procesado.

Rechaza lo inválido con código y mensaje mínimos. No devuelvas trazas, nombres de tablas ni secretos.

Un orden razonable:

1. Comprobar método.
2. Comprobar content type.
3. Comprobar autenticación o firma.
4. Comprobar tamaño.
5. Parsear JSON.
6. Validar event_type.
7. Validar campos obligatorios.
8. Comprobar duplicado.
9. Registrar recepción.
10. Responder.

Si el payload falla en el paso 3, no sigas mirando datos. Si falla en el paso 8, no ejecutes acciones de negocio. Esto mantiene el workflow legible y reduce daños.

Validación de firma

Algunos proveedores firman el body con una cabecera. La lógica exacta depende del proveedor, pero el patrón suele ser:

1. Recibir body sin modificar.
2. Leer cabecera de firma.
3. Calcular firma con secreto compartido.
4. Comparar de forma segura.
5. Rechazar si no coincide.

Si n8n o el nodo no ofrece una validación nativa para ese proveedor, puedes usar Code node de forma acotada. No metas toda la lógica de negocio en ese Code node: solo la verificación.

La referencia de HTTP Request en n8n también es útil para entender métodos, cabeceras y cuerpos cuando el flujo además necesita llamar a otra API.

Paso 5: responde de forma deliberada

Con Respond to Webhook puedes devolver JSON, texto o binario. Un patrón útil:

1. Webhook recibe.
2. Validación técnica.
3. Registro del identificador.
4. Respuesta 202 Accepted.
5. Procesamiento posterior.

Si el proveedor exige respuesta rápida, separa recepción de trabajo pesado. No hagas esperar a una API externa mientras generas documentos o llamas a varios servicios.

Responder rápido o esperar al resultado

Hay dos patrones:

Para leads, suele bastar con validar y responder rápido. Para facturas o pedidos, conviene registrar recepción y procesar con controles. Si el emisor reintenta por timeout, una ejecución lenta puede duplicar acciones si no hay idempotencia.

Paso 6: trata duplicados

Los webhooks se repiten. Guarda event_id o una clave equivalente y comprueba si ya fue procesada. Diferencia:

• recibido;
• validado;
• en proceso;
• completado;
• error recuperable;
• error definitivo.

Responder dos veces no debe crear dos facturas, contactos o mensajes.

Idempotencia explicada con un ejemplo

Imagina que Stripe, Shopify o un formulario reintenta el mismo evento porque no recibió respuesta. Sin control, n8n podría crear dos oportunidades, mandar dos mensajes o preparar dos facturas.

Con idempotencia:

1. Llega evt_123.
2. Buscas evt_123 en tu registro.
3. Si no existe, procesas y guardas estado.
4. Si existe, devuelves el resultado anterior o lo marcas como duplicado.

La clave idempotente debe ser estable. No uses la hora exacta de recepción en n8n como identificador, porque cada reintento tendrá una hora distinta.

Dónde guardar el estado

Opciones:

• base de datos;
• CRM;
• hoja controlada;
• sistema de origen;
• Data Store si encaja;
• tabla interna del proyecto.

Para pruebas, una hoja puede servir. Para producción con facturas, pedidos o mensajes, usa un sistema más robusto y con permisos claros.

Paso 7: prueba los fallos

Envía:

• JSON correcto;
• firma errónea;
• campo ausente;
• evento no permitido;
• mismo ID dos veces;
• body excesivo;
• servicio destino caído.

La plantilla webhook de lead validado muestra un recorrido educativo de entrada, normalización, If y dos respuestas. Revísala antes de importar.

Paso 8: conecta el destino con prudencia

Cuando la recepción ya está probada, conecta el sistema destino. Ejemplos:

• CRM para crear una oportunidad;
• Holded para preparar un documento;
• email para avisar al equipo;
• WhatsApp para registrar una conversación;
• Google Sheets para una prueba temporal;
• una API propia para abrir una tarea.

Empieza con una acción reversible. Crear una tarea interna es más prudente que enviar un mensaje al cliente. Preparar un borrador es más prudente que emitir una factura final.

Paso 9: registra evidencia

Cada evento importante debería dejar:

• ID recibido;
• fecha;
• tipo;
• resultado de validación;
• acción realizada;
• sistema destino;
• error si lo hubo;
• responsable si quedó en revisión.

Sin evidencia, no podrás saber si el webhook falló, si el proveedor reintentó o si una persona borró algo después.

Webhooks para WhatsApp

En WhatsApp, el webhook puede recibir mensajes o estados. La parte técnica es solo una capa. También importan consentimiento, plantillas, ventana de conversación, datos sensibles y salida humana.

Un primer flujo responsable:

1. Recibe evento.
2. Valida firma.
3. Clasifica intención.
4. Registra solicitud.
5. Avisa a una persona.
6. No responde automáticamente si la confianza es baja.

Desarrollamos el caso en automatizar WhatsApp para empresas.

Webhooks para facturación

Un evento invoice.requested no debería emitir una factura final sin controles. Primero valida cliente, NIF, conceptos, impuestos, moneda y estado del pedido. Después prepara borrador o tarea de revisión.

Para este escenario, consulta automatizar facturas con Holded y n8n.

Webhooks para formularios SEO y marketing

Un formulario de una landing puede enviar datos a n8n. Un buen flujo:

• valida campos;
• detecta spam básico;
• clasifica servicio;
• añade UTM;
• crea oportunidad;
• avisa al responsable;
• registra fuente;
• evita duplicados.

Para una agencia, esto no es solo operación. También mejora medición: sabes qué campaña, página o consulta generó el contacto.

Seguridad mínima

Un webhook público debe tener:

• HTTPS;
• autenticación o firma;
• ruta estable;
• límite de tamaño;
• lista de eventos permitidos;
• validación de schema;
• control de duplicados;
• registro de errores;
• respuesta sin datos internos;
• política de retención.

La documentación oficial de seguridad en n8n ayuda a revisar controles de despliegue, autenticación e instalación cuando el webhook vive en una instancia autoalojada.

Errores que veo a menudo

Usar la URL de test en producción

Funciona durante la prueba y luego deja de escuchar. Configura la URL de producción cuando el workflow esté activo.

Responder demasiado tarde

Si tardas más de lo que el proveedor permite, reintentará. Si no hay idempotencia, duplicarás acciones.

No validar eventos

Aceptar cualquier event_type convierte el webhook en una caja negra. Solo procesa lo que has definido.

Confiar en que nadie encontrará la URL

La oscuridad no es seguridad. Una URL puede filtrarse en logs, capturas, documentación o historial.

Guardar payloads completos sin criterio

Guardar todo facilita depuración, pero también aumenta riesgo y almacenamiento. Define retención.

Activar acciones finales desde el primer día

Primero registra y avisa. Después crea borradores. Más tarde automatiza efectos finales si el proceso lo justifica.

Cómo probar con curl

Puedes probar desde terminal:

curl -X POST "https://tu-n8n.example.com/webhook/lead-intake-v1" \
  -H "Content-Type: application/json" \
  -H "X-Test-Signature: ejemplo" \
  -d '{"event_id":"evt_test_001","event_type":"lead.created","data":{"email":"test@example.com"}}'

No pegues tokens reales en comandos compartidos. Para pruebas internas, usa variables de entorno o un entorno temporal.

Cómo probar con una herramienta externa

También puedes usar herramientas de prueba de webhooks o el sistema origen en modo sandbox. La ventaja es ver cómo envía realmente el proveedor. La desventaja es que puedes perder control si no sabes qué datos manda. Por eso conviene empezar con payloads anonimizados y endpoints de prueba.

Cómo versionar un webhook sin romper nada

Un webhook que ya recibe datos no debería cambiar de forma silenciosa. Si hoy aceptas lead.created con email y phone, no añadas mañana un campo obligatorio nuevo sin avisar al sistema origen. Lo prudente es versionar la ruta o el contrato:

/webhook/lead-intake-v1
/webhook/lead-intake-v2

La versión v1 sigue atendiendo a los sistemas actuales y v2 recibe el modelo nuevo. Cuando todos los emisores estén migrados, puedes retirar la versión antigua. Esto evita una situación muy frecuente: un formulario se actualiza, el workflow empieza a rechazar leads y nadie se entera hasta revisar el CRM.

La versión también ayuda a la IA y al equipo humano. Si documentas cada endpoint con nombre, evento, campos y destino, cualquier persona puede entender qué proceso está vivo, qué proceso está en pruebas y qué proceso ya no debe usarse.

Qué hacer cuando un proveedor reintenta

Muchos proveedores reintentan un webhook si no reciben una respuesta clara. Eso es bueno para resiliencia, pero peligroso si tu flujo crea acciones no idempotentes. Un pago, una factura, una tarea comercial o una cita no pueden duplicarse porque el primer intento tardó demasiado.

La defensa es triple:

• responder rápido;
• guardar una clave única del evento;
• comprobar esa clave antes de ejecutar la acción final.

Si el mismo event_id llega dos veces, el workflow debe reconocerlo y contestar sin repetir la escritura. En negocios pequeños este detalle parece excesivo hasta que una automatización crea dos facturas, dos mensajes al cliente o dos tareas para el equipo. La calidad de una automatización se nota justo en estos bordes.

Qué hacer si el sistema destino cae

No todos los fallos deben bloquear al usuario. Si el webhook recibe un lead y el CRM está caído, tienes varias opciones:

• guardar el evento en una cola temporal;
• enviar una alerta interna;
• reintentar con límite;
• crear una tarea manual;
• responder al origen con aceptación si el dato ya quedó registrado.

Lo que no conviene es perder el payload o dejar el workflow fallando sin responsable. Un webhook profesional separa recepción, validación, persistencia y entrega. Así, aunque el destino falle, el negocio conserva el dato y puede recuperarlo.

Cómo diseñarlo para auditoría

Cada ejecución importante debería dejar una evidencia mínima:

• hora recibida;
• origen;
• evento;
• identificador externo;
• validación aplicada;
• destino escrito;
• resultado;
• error si lo hubo.

No hace falta guardar datos personales sin necesidad. Para muchos casos basta con un identificador, un resumen y el estado. Lo importante es poder contestar a una pregunta simple: “¿qué pasó con este formulario, pago, mensaje o pedido?”.

Webhooks para SEO, GEO y AIO

Un webhook también puede alimentar posicionamiento. Por ejemplo, cuando entra una nueva reseña, un caso de éxito aprobado o una pregunta frecuente real de un cliente, el evento puede abrir una tarea editorial. No se publica solo: se registra la señal, se propone una respuesta y una persona valida si merece convertirse en contenido.

Ese enfoque convierte la web en un sistema vivo. Las preguntas reales de clientes terminan en FAQ, los problemas repetidos terminan en guías, y los casos de éxito terminan en prueba social. Para SEO tradicional ayuda porque amplía cobertura long tail. Para GEO/AIO ayuda porque el contenido se vuelve más extractable: respuestas concretas, contexto real y trazabilidad.

Cuándo no usar webhook

No todo necesita webhook. Si un proceso ocurre una vez al mes, no exige respuesta inmediata y puede importarse desde un CSV controlado, quizá no merece una integración en tiempo real. Si el proveedor no documenta eventos, no firma peticiones y cambia campos sin aviso, quizá conviene empezar con una automatización supervisada.

La pregunta no es “¿se puede automatizar?”. Casi siempre se puede. La pregunta buena es: “¿qué pasa si falla, se duplica o llega tarde?”. Si la respuesta es grave, hay que diseñar con más cuidado.

Pregunta de negocio antes de construir

Antes de abrir n8n, define una frase: “cuando ocurra X, queremos que pase Y, salvo si Z”. Esa frase evita automatizaciones bonitas pero inútiles. Por ejemplo: “cuando entre un formulario de presupuesto, queremos crear una oportunidad y avisar al equipo, salvo si falta email o teléfono”. Con esa regla ya sabes qué validar, qué guardar, qué responder y cuándo pedir intervención humana.

Qué documentar

Documenta:

• URL de producción;
• sistema origen;
• evento;
• método;
• autenticación;
• campos obligatorios;
• respuesta esperada;
• política de reintentos;
• clave idempotente;
• destino;
• responsable;
• procedimiento de pausa.

Si mañana el webhook falla, esta documentación ahorra horas.

Checklist de producción

• HTTPS válido.
• Autenticación o firma verificada.
• Lista explícita de eventos.
• Validación antes de cualquier escritura.
• Idempotencia por identificador estable.
• Respuesta rápida y no reveladora.
• Límites de tamaño y frecuencia.
• Error workflow y alerta.
• Retención de payloads justificada.

CTA

El siguiente nivel es transformar datos y usar expresiones. Para un flujo conectado a CRM, ERP o WhatsApp, consulta automatizaciones n8n.

Si tu empresa ya recibe formularios, WhatsApp, pedidos o eventos de pago y no sabes si automatizarlos, podemos revisar el proceso y definir un primer webhook seguro. No hace falta empezar grande: un flujo básico desde 99 euros puede validar una entrada, registrar evidencia y avisar al equipo sin tocar todavía sistemas críticos.