Módulo 04

El Timbre del Sistema (Webhooks)

Deja de preguntar "¿hay novedades?" y empieza a recibir avisos en tiempo real.

Fase 2 · n8n ~50 min Práctica guiada
1

La Analogía del Portero (Webhook vs Polling)

Imagina tu casa. Tienes dos formas de saber si llegó un paquete: webhook = el cartero toca el timbre y te avisa; polling = abres la puerta cada 5 minutos a ver si llegó algo. Ambos funcionan, pero solo el primero respeta tu tiempo.

Arquitectura del timbre

  • Webhook: el otro sistema hace POST a tu URL cuando ocurre el evento. Tú no preguntas, te empujan.
  • Polling: tu sistema hace GET cada N segundos/minutos. Gasta recursos aunque no haya nada nuevo.
  • Costo: 1000 eventos/hora vía webhook = 1000 peticiones que recibes. Vía polling = 1000 + N consultas inútiles.

Regla práctica que uso en GabyMatic: si el otro sistema soporta webhook, úsalo. Polling solo cuando no hay alternativa (ej. bancos viejos, APIs sin eventos).

2

Cómo funciona un Webhook por dentro

Un webhook no es magia. Es una URL HTTP pública que tu n8n expone y donde otro sistema hace POST con un JSON. Lo que llega es lo que disparará tu workflow.

Anatomía de un POST entrante

// El otro sistema envía
POST https://tu-n8n.com/webhook/lead-nuevo
Content-Type: application/json

{
  "nombre": "Carolina",
  "email": "caro@example.com",
  "monto": 250000
}

// n8n recibe y lo entrega como $json.body
$json.body.nombre   → "Carolina"
$json.body.email    → "caro@example.com"
$json.body.monto    → 250000
3

Las 4 partes del nodo Webhook

Configurar el Webhook Trigger en n8n v2.x tiene cuatro controles clave. Toca los cuatro y entenderás qué hace cada uno.

  1. 1

    HTTP Method

    Casi siempre POST (el estándar para enviar datos). También soporta GET si quieres devolver info.

  2. 2

    Path

    Nombre único que identifica tu webhook en la URL. Ej: lead-nuevo → https://tu-n8n.com/webhook/lead-nuevo.

  3. 3

    Authentication

    None para pruebas, Header Auth para producción (comparte un secreto en headers).

  4. 4

    Respond

    Define si n8n responde al remitente (200 OK + JSON) o solo recibe y procesa.

Test URL vs Production URL

n8n te da dos URLs por nodo webhook:

  • Test URL: /webhook-test/. Solo funciona mientras tienes el editor abierto. Úsala mientras diseñas.
  • Production URL: /webhook/. Funciona siempre que el workflow esté activado (toggle "Active" en verde).
4

Recibir datos desde Postman (paso a paso)

Postman es el simulador perfecto: tú eres "el otro sistema" y envías POST a tu propio n8n. Es la forma más rápida de validar que el webhook está vivo.

  1. Crea un workflow nuevo, agrega un Webhook trigger con método POST y path lab-04.
  2. Clic en "Listen for test event" (el botón que aparece en el nodo). n8n queda esperando un POST.
  3. Copia la Test URL que muestra n8n (algo como https://n8n.gabymatic.com/webhook-test/lab-04).
  4. Abre Postman → nueva petición POST → pega la URL → Body → raw → JSON.
  5. Escribe un payload válido: {"test": "hola", "usuario": "Gabriel", "monto": 45000} → clic Send.
  6. Vuelve a n8n: verás el panel INPUT del Webhook con tu JSON. Acepta el test event y conecta el siguiente nodo.

Error común #1

No hacer clic en "Listen for test event" antes de enviar desde Postman. El flujo "escucha" solo durante esa ventana de prueba. Si lo olvidas, Postman recibe un 404 y tú te quedas mirando el log sin entender nada.

Error común #2

Enviar el JSON con un método equivocado. Si tu webhook está en POST y Postman manda GET, n8n responde 405 Method Not Allowed. Verifica siempre la pestaña de método antes de copiar/pegar URLs entre proyectos.

Error común #3

Olvidar devolver un 200. Si tu webhook queda en estado "Waiting for response" infinito, casi siempre es porque configuraste Respond When = "Using 'Respond to Webhook' node" pero no agregaste ese nodo al final. Sin respuesta 200, el sistema que llamó se queda colgado pensando que falló.

5

Práctica guiada: Webhook → Set → fin

Objetivo: crear un webhook, enviarle JSON desde Postman y ver cómo los datos aparecen dentro de n8n.

  1. Workflow Crea un workflow llamado lab-04-webhook. Trigger: Webhook. Method: POST. Path: lab-04. Authentication: None.
  2. Activar escucha Haz clic en Listen for test event y copia la Test URL.
  3. Enviar POST En Postman: POST a la Test URL. Body JSON: {"lead": {"nombre": "Ana", "email": "ana@x.com", "valor": 120000}}.
  4. Verificar INPUT En n8n verás el panel INPUT con {"lead": {...}}. Acepta el test.
  5. Nodo Set Agrega un nodo Set. Mapea nombre → {{$json.body.lead.nombre}} y valor → {{$json.body.lead.valor}}.
  6. Resultado Revisa el output del Set. Deberías ver dos campos limpios: nombre: "Ana", valor: 120000.
6

Checklist del Módulo 04

Desafío del módulo

Recibe un lead desde Postman y devuélvelo transformado

Simula que tu webhook es la entrada de un CRM real. Tu misión:

  1. Crea el webhook /lead-entrada con método POST y autenticación Header Auth (clave: X-Secret, valor: gabymatic-2026).
  2. En Postman agrega el header X-Secret: gabymatic-2026 y envía: {"lead": {"nombre": "Pedro", "email": "p@x.com", "valor": 85000, "moneda": "COP"}}.
  3. Agrega un nodo Set que arme el JSON de respuesta: { "mensaje": "Lead Pedro recibido por 85000 COP", "status": "ok" }.
  4. Agrega un nodo Respond to Webhook al final con status 200 y body usando las variables del Set.
  5. Ejecuta: Postman debe recibir el 200 con tu JSON transformado.

Bonus: agrega un nodo IF que rechace (status 401) si el header X-Secret no coincide. Aprendes autenticación real.