Dispara un flujo de n8n desde un agente de Claude por webhook

Un agente que solo conversa es un callejón sin salida, muy educado pero sin salida. En el momento en que quieres que haga algo (mandarle un correo a un cliente, escribir una fila, arrancar un deploy) te topas con una pregunta de fondo: ¿cómo le das la capacidad de actuar sin ponerle a un modelo de lenguaje credenciales en crudo y un cheque en blanco en la mano? La respuesta limpia es un webhook por delante de un flujo de n8n. El agente llama a una URL con un body JSON pequeño; n8n se queda con todos los secretos y corre el trabajo de verdad detrás de una frontera autenticada que controlas tú. Esta guía arma esa frontera de punta a punta: el flujo, la autenticación, la herramienta del lado del agente, un ejemplo completo y los tropiezos que convierten una configuración de cinco minutos en una tarde rascándote la cabeza.

01 · Requisitos previos y la frontera que vas a armar

Antes de hacer clic en nada, deja esto listo:

• Una instancia de n8n corriendo a la que puedas llegar por HTTPS. Self-hosted en un VPS o n8n Cloud: las dos sirven. El único requisito firme es que el runtime del agente alcance la URL.
• Credenciales configuradas dentro de n8n para lo que el flujo vaya a hacer de verdad: una conexión OAuth de Gmail, una credencial de Postgres, una key de Stripe. Móntalas en el almacén de credenciales de n8n, no en variables de entorno que el agente pueda leer.
• Un agente capaz de llamar a una herramienta HTTP. Con Claude eso es o una herramienta que defines en la API (una función que el modelo puede invocar) o un servidor MCP que expone la capacidad de hacer llamadas HTTP. En cualquiera de los dos casos, el agente termina mandando un request POST.
• Un secreto compartido que vas a generar ahora y guardar en algún lugar que el código del agente pueda leer pero su prompt no. Un string aleatorio largo es suficiente.

El modelo mental cabe en una frase: el agente está afuera de un muro, n8n está adentro y el webhook es la única puerta. Todo lo peligroso (las credenciales, el destino, la acción irreversible) vive detrás del muro. Al agente le toca un timbre y una llave, nada más.

02 · Arma el flujo que vive detrás del webhook

Abre n8n y crea un flujo nuevo. El primer nodo es un trigger Webhook.

Configura el trigger

1. Agrega un nodo Webhook como trigger inicial.
2. Pon el método HTTP en POST. A un efecto secundario nunca debería llegarle un GET suelto disparado por un crawler o por el preview de un enlace.
3. Dale un path estable y difícil de adivinar. n8n genera uno; déjalo o pon el tuyo. Trata el path como un secreto de poca monta: no es tu autenticación, pero tampoco hay razón para andarlo publicando.
4. Fíjate en que el nodo muestra dos URLs: una Test URL y una Production URL. Más adelante vas a conectar el agente a la de producción. Esta diferencia es la causa más común del "funcionó en el editor y después se murió", que vemos en la sección 06.

Valida antes de actuar

El siguiente nodo debería revisar el payload antes de que corra algo irreversible. La idea es fallar fuerte y claro: una llamada mal armada devuelve un error nítido en vez de ejecutarse a medias y dejarte un efecto secundario a medio hacer. Agrega un nodo Code pequeño (o un nodo IF) que valide los campos que exiges y lance un error si falta alguno.

// Primer nodo después del webhook. Rechaza lo que no venga bien formado.
const body = $input.first().json.body ?? {};

const required = ["subject", "message", "ticketId"];
const missing = required.filter((k) => !body[k]);

if (missing.length) {
  // Sale como un 400 al que llama en vez de fallar dentro del flujo.
  throw new Error("payload inválido, falta: " + missing.join(", "));
}

return [{ json: body }];

Haz el trabajo de verdad

Después de validar, agrega los nodos que ejecutan la acción: un nodo de Gmail "enviar", un "insert" de Postgres, un request HTTP a un servicio interno. Aquí es donde se usan tus credenciales de n8n, todo dentro del muro. El agente nunca las toca.

Cierra con un nodo Respond to Webhook que devuelva un resultado corto y honesto: un estado y, si acaso, un id. El agente va a leer esto para saber si su acción salió bien, así que déjalo sin ambigüedad.

03 · Cierra la puerta: autenticación

Un webhook sin autenticar que ejecuta un efecto secundario es un botón público que aprieta cualquiera que se entere de la URL. n8n trae Header Auth integrado en el nodo Webhook: úsalo.

1. En el nodo Webhook, pon Authentication en Header Auth.
2. Crea una credencial Header Auth en n8n: un nombre de header (por ejemplo x-webhook-token) y el valor apuntando a tu secreto compartido.
3. A partir de ahí, n8n rechaza cualquier request que no traiga ese header o que traiga el valor equivocado, antes incluso de que tu flujo arranque. Ese rechazo es la falla más barata que hay: no corre ningún nodo y no se toca ninguna credencial.

Unas cuantas reglas que pesan más de lo que parece:

• El secreto vive en dos lugares, nada más: el almacén de credenciales de n8n y la config del runtime del agente. Nunca en el prompt, nunca en la descripción de una herramienta, nunca en un string que vas a subir al repo.
• Para rotarlo, cambias el valor de la credencial y la config del runtime al mismo tiempo. Como el agente lee el token de la config y no de su memoria, rotar es un cambio de config, no un redeploy de prompts.
• Mejor un header que un token en el query string. Los query strings van a parar a los logs de acceso y de proxy mucho más fácil que los headers.

04 · Conecta el agente: define la herramienta, no la URL

Vamos ahora al lado del agente. El principio es este: el agente recibe una capacidad con una forma bien acotada, no un cliente HTTP de uso general. Expones una sola función cuyas únicas entradas son los parámetros seguros; la URL, el token y el método quedan fijos en código que el modelo no puede reescribir.

// El agente puede llamar esto. No puede ver WEBHOOK_URL ni SHARED_TOKEN;
// esos vienen del entorno del runtime, nunca del modelo.
const WEBHOOK_URL = process.env.N8N_WEBHOOK_URL!;
const SHARED_TOKEN = process.env.N8N_WEBHOOK_TOKEN!;

type ReplyInput = { ticketId: string; subject: string; message: string };

export async function sendSupportReply(input: ReplyInput) {
  const res = await fetch(WEBHOOK_URL, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-webhook-token": SHARED_TOKEN,
    },
    body: JSON.stringify(input),
  });

  if (!res.ok) {
    // Dale al agente una falla clara y sin secretos sobre la que pueda razonar.
    throw new Error("la automatización falló: HTTP " + res.status);
  }
  return res.json();
}

Cuando registres esto con Claude, ya sea como una definición de herramienta en la API o detrás de un servidor MCP, describe sus entradas con precisión (ticketId, subject, message) y nada sobre el transporte. El modelo decide qué decir en la respuesta; tu código decide a dónde va y cómo se autoriza. En esa separación está todo el diseño.

Y si lo haces vía MCP

Si vas por un servidor MCP en vez de una herramienta escrita a mano, la regla es la misma: el dueño de la URL y del token es el servidor, no el modelo. Una herramienta MCP genérica del tipo "trae cualquier URL" vuelve a abrir el hueco que acabas de tapar, porque al modelo lo pueden convencer de apuntarla a donde sea. Mejor una herramienta MCP hecha a la medida, o un servidor wrapper delgado que solo sepa llamar a tu webhook con tu secreto y que exponga únicamente los parámetros seguros en su schema.

05 · Un ejemplo completo, de principio a fin

Digamos que un agente de soporte tiene que poder mandar una respuesta con plantilla a un ticket. Aquí va el ciclo completo.

1. En n8n: Webhook (POST, Header Auth) hacia Code (validar ticketId, subject, message) hacia Gmail "enviar" (usando una credencial de Gmail de n8n) hacia Respond to Webhook devolviendo «{ "ok": true, "messageId": "..." }».
2. Genera el secreto y ponlo donde los dos lados puedan leerlo sin que llegue nunca a un prompt:

# Genera un token y guárdalo en la credencial Header Auth de n8n
# y en el env del runtime del agente (p. ej. un .env que no commiteas).
openssl rand -hex 32

3. Activa el flujo. Ponlo en Active dentro de n8n. Esto no es opcional: la URL de producción solo responde cuando el flujo está activo (mira la sección 06).
4. Configura el runtime del agente con N8N_WEBHOOK_URL (la URL de producción) y N8N_WEBHOOK_TOKEN (el secreto). Registra sendSupportReply como herramienta.
5. Pruébalo. Pídele al agente que responda al ticket 4821 confirmando que un reembolso está en proceso. El modelo redacta el mensaje y llama a la herramienta; n8n autentica, valida, envía con tu credencial de Gmail y devuelve el id del mensaje; el agente reporta que salió bien.
6. Lee el resultado. Como el flujo devuelve un estado y un id reales, el agente puede decir "enviado, id abc123" en lugar de adivinar. Si n8n devolvió un 400, el agente se entera de que el payload venía mal y puede corregirlo y reintentar, todo sin haber visto jamás una credencial.

La credencial nunca salió de n8n. La lógica del destino nunca salió de tu flujo. El agente hizo exactamente una cosa: rellenó los parámetros seguros y tocó el timbre.

06 · Tropiezos típicos y cómo depurarlos

Estas son las fallas que de verdad te vas a encontrar, más o menos en orden de frecuencia.

• Llamar a la URL de test. La Test URL del nodo Webhook solo responde con el editor abierto y escuchando; se muere apenas lo cierras. Síntoma: funciona mientras lo miras y devuelve 404 en producción. Solución: usa la Production URL y asegúrate de que el flujo esté en Active.
• Flujo sin activar. Una URL de producción perfectamente correcta devuelve 404 si el toggle del flujo está apagado. Cada vez que te dé 404 en una URL que sabes que está bien, revisa primero el switch de Active.
• 401 de la capa de autenticación. El nombre o el valor del header no coincide con la credencial Header Auth. Compara el nombre exacto del header (mayúsculas y todo) y confirma que el runtime esté leyendo el secreto que crees. Imprime su longitud, no su valor.
• 400 de tu validador. Esto es el sistema funcionando como debe. Lee el mensaje, que te dice qué campo falta. Casi siempre el agente mandó una clave un poco distinta de la que espera tu nodo Code, así que alinea el schema de entrada de la herramienta con el validador.
• El efecto secundario se ejecutó pero no volvió respuesta. Se te quedó pendiente el nodo Respond to Webhook, así que el agente se quedó esperando o recibió un body vacío y no puede distinguir si fue éxito o fracaso. Cierra siempre el ciclo con una respuesta explícita.
• Ejecución parcial silenciosa. Una llamada corrió a medias antes de fallar porque la validación quedó después de un nodo de acción. Pon la validación primero; nada irreversible debería correr antes de comprobar que el payload viene bien.

Bien hecho, este patrón te da lo que vuelve de verdad útiles a los agentes (la acción real) sin lo que los vuelve peligrosos (el acceso sin acotar). El webhook es una puerta angosta, autenticada y auditable, y todo lo que queda detrás sigue siendo tuyo. Arma la puerta con cabeza, mantén el secreto fuera del alcance del modelo y deja que el agente toque el timbre.