Webhooks entrantes: Activación de workflows externos

Los webhooks entrantes son el mecanismo principal para que n8n reciba datos de sistemas externos de forma asíncrona. Actúan como un punto de entrada que desencadena la ejecución de un workflow, permitiendo automatizar respuestas a eventos en tiempo real. Entender su configuración y operación es fundamental para construir integraciones reactivas.

El webhook como punto de entrada asíncrono

Un webhook entrante en n8n es una URL única que, al recibir una solicitud HTTP (generalmente POST o GET), inicia la ejecución de un workflow. A diferencia de las solicitudes API tradicionales, donde el cliente consulta activamente un servidor, un webhook es un mecanismo de push: el sistema externo notifica a n8n cuando ocurre un evento relevante. Esto es eficiente porque n8n no necesita sondear constantemente el sistema externo para detectar cambios, reduciendo la carga y la latencia.

Cuando un sistema externo envía datos a la URL del webhook, n8n captura esa información y la inyecta como el primer nodo del workflow. A partir de ahí, los nodos subsiguientes pueden procesar, transformar y actuar sobre esos datos. Esta capacidad asíncrona es clave para escenarios como:

• Recibir notificaciones de nuevos registros en una base de datos.
• Procesar pagos exitosos de una pasarela de pago.
• Automatizar respuestas a eventos en sistemas de monitoreo o CRM.
• Integrar sistemas que no ofrecen APIs REST completas, pero sí la capacidad de enviar webhooks.

Configuración de un nodo Webhook

Para configurar un webhook en n8n, se utiliza el nodo 'Webhook'. Este nodo siempre es el primer nodo en un workflow que se espera sea activado por un evento externo. Los pasos básicos son:

1. Añadir el nodo Webhook: Búscalo en el panel de nodos y arrástralo al lienzo. Será automáticamente el nodo de inicio.
2. Definir el método HTTP: Selecciona el método que esperas recibir (GET, POST, PUT, DELETE). POST es el más común para enviar datos, GET para consultas simples o validaciones.
3. Configurar la URL del Webhook: n8n generará una URL única. Esta URL es la que debes copiar y configurar en el sistema externo que enviará los datos. Puedes elegir entre una URL de prueba (para desarrollo y depuración) y una URL de producción (para uso en vivo).
4. Modo de respuesta (Response Mode): Define cómo n8n responderá a la solicitud del webhook. Las opciones comunes son 'No Response' (n8n procesa y no envía nada de vuelta), 'Last Node' (la salida del último nodo del workflow se envía como respuesta), o 'Custom' (permite definir una respuesta específica, incluyendo código de estado HTTP y cuerpo de la respuesta).
5. Autenticación (Opcional): Para mayor seguridad, puedes configurar autenticación básica o de cabecera. Esto requiere que el sistema externo incluya credenciales válidas en su solicitud para que n8n acepte los datos.

Procesamiento de datos entrantes

Una vez que el nodo Webhook recibe una solicitud, los datos se convierten en la entrada para los nodos subsiguientes. La estructura de los datos dependerá del formato enviado por el sistema externo (JSON, FormData, URL-encoded, texto plano). n8n parsea automáticamente los formatos JSON y URL-encoded.

Puedes acceder a estos datos utilizando expresiones en nodos posteriores. Por ejemplo, si un webhook recibe un JSON con un campo "id_pedido", puedes referenciarlo con {{ $json.id_pedido }}. El nodo Webhook también expone información sobre la solicitud HTTP, como las cabeceras ({{ $json.headers }}) y los parámetros de consulta ({{ $json.query }}).

{
  "body": {
    "id_evento": "EVT-2023-10-26-001",
    "tipo": "nuevo_registro",
    "datos": {
      "nombre": "Juan Pérez",
      "email": "[email protected]"
    },
    "timestamp": "2023-10-26T10:30:00Z"
  },
  "headers": {
    "content-type": "application/json",
    "user-agent": "SistemaExterno/1.0"
  },
  "query": {
    "token": "abc123xyz"
  }
}

El ejemplo anterior muestra la estructura de datos que un nodo Webhook podría recibir. El objeto body contiene la carga útil principal, mientras que headers y query proporcionan metadatos de la solicitud. Es crucial inspeccionar la salida del nodo Webhook en modo de prueba para entender la estructura exacta de los datos que se están recibiendo y así poder referenciarlos correctamente en el workflow.

Webhooks en entornos de producción y desarrollo

La distinción entre URLs de prueba y producción es fundamental. La URL de prueba es útil para depurar el workflow sin afectar la integración en vivo. Cada vez que guardas y activas un workflow, n8n genera una nueva URL de prueba. La URL de producción, en cambio, es estática una vez que el workflow se activa por primera vez y se mantiene constante a menos que se cambie explícitamente la configuración del nodo.

Para activar un webhook en producción, el workflow debe estar activo. Un workflow activo con un nodo Webhook de producción escuchará continuamente las solicitudes entrantes. Si el workflow se desactiva, la URL de producción dejará de funcionar hasta que se reactive.

Aplicación práctica: Integración de notificaciones de un sistema de tickets

El lunes, identifica un sistema en tu entorno que genere notificaciones de eventos y que tenga la capacidad de enviar webhooks. Puede ser un sistema de monitoreo, un CRM, o un sistema de gestión de tickets.

1. Paso 1: Identificar el evento: Selecciona un evento específico, por ejemplo, 'nuevo ticket creado' o 'estado de ticket actualizado'.
2. Paso 2: Crear el workflow en n8n: Inicia un nuevo workflow y añade un nodo 'Webhook'. Configúralo para recibir solicitudes POST (es lo más común para notificaciones).
3. Paso 3: Obtener la URL del webhook: Copia la URL de prueba generada por n8n.
4. Paso 4: Configurar el sistema externo: Accede a la configuración del sistema de tickets y pega la URL del webhook en la sección de notificaciones o webhooks. Configura el sistema para que envíe una notificación cuando ocurra el evento elegido.
5. Paso 5: Probar y depurar: Desencadena el evento en el sistema de tickets (ej. crea un nuevo ticket). Observa la ejecución en n8n para verificar que el webhook reciba los datos correctamente. Utiliza nodos como 'Set' o 'Code' para inspeccionar la estructura de los datos entrantes. Ajusta el workflow para extraer la información relevante (ID del ticket, asunto, descripción, etc.).
6. Paso 6: Definir una acción: Añade un nodo posterior que realice una acción útil, como enviar una notificación a un canal de Teams o Slack, o crear un registro en una base de datos interna con la información del ticket. Esto validará la cadena completa de la integración.