Qué es un webhook y por qué importa

La mayoría de las integraciones con APIs son basadas en pull: tu flujo de trabajo se ejecuta según una programación, llama a un servicio externo y obtiene lo que haya cambiado desde la última comprobación. Los webhooks invierten ese modelo. En lugar de que tú preguntes, el servicio externo te envía los datos en el momento en que algo ocurre — un pago se completa, un formulario se envía, un repositorio recibe un nuevo commit. El resultado es una reacción casi instantánea sin sobrecarga de polling.

n8n tiene un nodo Webhook integrado que convierte cualquier flujo de trabajo en un endpoint HTTP. Cuando ese endpoint recibe una solicitud, el flujo de trabajo se dispara de inmediato. Esta lección explica cómo configurarlo, manejar el payload entrante y enviar una respuesta adecuada de vuelta al llamante.

Configurar el nodo Webhook

Arrastra un nodo Webhook al canvas y configúralo como disparador (primer nodo). Los dos ajustes que configuras de inmediato son el Método HTTP y el Path.

El Método HTTP es casi siempre POST — eso es lo que envía cualquier plataforma importante. Usa GET solo cuando el tercero lo documente explícitamente (algunos handshakes de verificación usan GET).

El Path es el slug único que identifica este flujo de trabajo. n8n genera un UUID por defecto, pero puedes poner algo legible como /stripe-events o /github-push. La URL completa que n8n te muestra tiene este aspecto:

https://your-n8n-instance.com/webhook/stripe-events

Pegas esa URL en la configuración de webhooks de la plataforma externa — panel de Stripe, ajustes del repo de GitHub, Typeform, el servicio que sea.

n8n te ofrece dos URLs de webhook por nodo: una Test URL y una Production URL. La Test URL solo está activa mientras estás en el editor con el flujo de trabajo abierto y escuchando. La Production URL solo está activa cuando el flujo de trabajo está guardado y activado. Nunca le des a un proveedor tu Test URL para una integración en producción — deja de funcionar en el momento en que cierres la pestaña del navegador.

Recibir y parsear el payload

Una vez que se dispara el webhook, los datos entrantes aterrizan en la salida del nodo Webhook. n8n parsea automáticamente los cuerpos JSON, así que si Stripe envía un evento payment_intent.succeeded, accedes al monto del cargo directamente en los nodos posteriores como una expresión:

{{ $json.data.object.amount }}

Para cuerpos form-encoded (algunos servicios antiguos envían Content-Type: application/x-www-form-urlencoded), n8n también los parsea automáticamente en el mismo objeto $json.

Las cabeceras también están disponibles, lo cual importa para la verificación de firma. Stripe, GitHub y la mayoría de plataformas serias firman sus payloads de webhook con un secreto HMAC para que puedas confirmar que la solicitud realmente proviene de ellas. En n8n puedes leer la cabecera de la firma dentro de un nodo Code y verificarla:

const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = $input.first().binary?.data
  ? Buffer.from($input.first().binary.data, 'base64').toString()
  : JSON.stringify($input.first().json);
const signature = $input.first().headers['x-hub-signature-256'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');
if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}
return $input.all();

Siempre valida las firmas en flujos de trabajo de producción que disparen acciones sensibles — enviar correos, modificar registros, cobrar a usuarios.

Responder al llamante

Algunas plataformas requieren una respuesta HTTP específica, no solo el 200 OK por defecto. Stripe espera un 200 en pocos segundos o reintenta. GitHub espera 200. Algunos sistemas como Typeform o servicios internos personalizados quieren un cuerpo JSON de vuelta confirmando la recepción.

En los ajustes del nodo Webhook, configura Response Mode como Last Node. Ahora el último nodo de tu flujo de trabajo controla lo que se envía de vuelta. Combínalo con un nodo Respond to Webhook al final de la cadena y configúralo:

{
  "statusCode": 200,
  "body": { "received": true, "id": "={{ $json.id }}" }
}

Si tu flujo de trabajo hace procesamiento pesado — escrituras en base de datos, envío de correos, llamadas a otras APIs — y aun así necesitas responder rápido, usa Response Mode: Immediately en el nodo Webhook. n8n devuelve 200 de inmediato y continúa ejecutando el resto del flujo de trabajo en segundo plano. La contraparte es que no puedes enviar un cuerpo de respuesta dinámico, pero el llamante nunca excede el tiempo de espera.

Errores comunes que debes evitar

Usar la Test URL en producción es el error más frecuente. El flujo de trabajo se queda en silencio en el momento en que cierras el editor y nadie se da cuenta hasta que se pierden eventos.

No manejar los reintentos es otra brecha. Stripe reintenta webhooks fallidos hasta 72 horas. Si tu flujo de trabajo no es idempotente — es decir, ejecutarlo dos veces sobre el mismo evento causa un registro duplicado o un doble cobro — necesitas comprobar si ya procesaste un ID de evento dado antes de hacer cualquier escritura.

Ignorar el tiempo de espera de la respuesta causa fallos silenciosos. Si tu flujo de trabajo tarda 30 segundos y el llamante espera una respuesta en 5, marca la entrega como fallida y reintenta, aunque tu flujo de trabajo termine teniendo éxito. Responde inmediatamente u optimiza la ruta de procesamiento.

Resumen

Los webhooks permiten que servicios externos envíen eventos a n8n en tiempo real, eliminando la necesidad de polling programado. Configuras un nodo Webhook con un path y método HTTP, pegas la Production URL en los ajustes del proveedor y luego accedes al payload a través de $json en los nodos posteriores. La verificación de firma protege contra solicitudes falsificadas, y el nodo Respond to Webhook o el modo Immediately te dan control sobre lo que el llamante recibe de vuelta. Hacer bien estos detalles — URL correcta, comprobación de firma, idempotencia, tiempo de respuesta — es lo que separa una integración frágil de una que funciona de forma fiable en producción.