Webhooks

Webhooks entrantes#

Cada disparador Webhook de una automatización tiene su propia URL pública. Al llamarla, la automatización corre con el cuerpo que envíes.

Obtener la URL

1. En el CRM, abre Automatizaciones y edita (o crea) el flujo.
2. Agrega el disparador Webhook y guarda la automatización al menos una vez.
3. Vuelve a abrir el nodo y copia la URL del webhook.
4. Activa la automatización: si está en borrador o pausada, la URL responde 400.

Llamarla

curl -X POST https://api.yavehome.com/api/v1/webhooks/automation/cm8ez1a2b/cm8ez9y8x \
  -H "Content-Type: application/json" \
  -d '{
    "lead": {
      "name": "Juan Pérez",
      "phone": "+573001112233",
      "email": "[email protected]"
    },
    "evento": "reserva_pagada",
    "utm_source": "google",
    "utm_campaign": "feria-vivienda"
  }'

Acepta cualquier JSON. También responde a GET (sin cuerpo), para proveedores que verifican la URL antes de enviar eventos.

Usar los datos en el flujo

Los nodos siguientes leen el cuerpo con variables. Con el ejemplo de arriba:

Por seguridad, los encabezados Authorization, Cookie y X-API-Key no se exponen al flujo.

Crear un lead desde el webhook

Conecta el disparador con la acción Crear lead y mapea nombre, teléfono y correo con variables. Sin configurar nada más, la acción toma del cuerpo los utm_*, gclid, gbraid, wbraid, fbclid, ttclid, referrer y landing_page, ya sea en el primer nivel o un nivel adentro ({"lead": {...}}, {"data": {...}}). Si el teléfono o el correo ya existen, no crea un duplicado.

Respuesta

{
  "executionId": "cm8f0k2…",
  "status": "completed",       // o "failed", con un campo "error"
  "nodeResults": [ … ]
}

Si un paso del flujo falla, la respuesta sigue siendo exitosa a nivel HTTP con status: "failed", para que tu proveedor no reintente en bucle. Errores HTTP: 404 si la automatización o el nodo no existen; 400 si el nodo no es un disparador Webhook o la automatización no está activa.

Webhooks salientes#

Para que YAVE avise a tu sistema, crea una automatización con el disparador que te interesa y agrega la acción Llamar Webhook. Disparadores habituales:

• Lead creado, lead actualizado, lead asignado.
• Cambio de etapa en el embudo, etiqueta agregada.
• Formulario enviado, lead desde Meta Ads, Google Ads o TikTok Ads.
• Cita agendada, confirmada o cancelada.
• Eventos de cartera: cuota vencida, pago registrado, entre otros.
• Programado (todos los días a cierta hora).

Configuración del nodo

Cuerpo estándar

{
  "event": null,
  "organizationId": "8c1d…",
  "lead": {
    "id": "b1f3c6e2-7a0d-4c1e-9d55-2f8e0a4b7c19",
    "name": "Laura Gómez",
    "email": "[email protected]",
    "phone": "+573001234567",
    "source": "LANDING",
    "originType": "WEBSITE_FORM",
    "status": "NEW",
    "score": 72,
    "budget": 350000000,
    "assignedToId": "5d0e9a41-…",
    "createdAt": "2026-09-29T14:03:11.000Z"
  }
}

status es el identificador de la etapa actual del lead y originType el canal de origen que calculó YAVE. event normalmente llega en null: si tu sistema necesita distinguir eventos, usa una URL distinta por automatización (por ejemplo ?evento=cambio_etapa) o un cuerpo personalizado. Trata todos los campos como opcionales: si el flujo no tiene un lead asociado, llegan vacíos.

Cuerpo personalizado

Útil cuando el sistema receptor espera sus propios nombres de campo (GoHighLevel, HubSpot, un ERP):

{
  "nombre": "{{lead.name}}",
  "telefono": "{{lead.phone}}",
  "correo": "{{lead.email}}",
  "origen": "{{lead.source}}",
  "yave_id": "{{lead.id}}"
}

Recibirlo de forma segura

• YAVE no firma las peticiones. Autentícalas con un secreto largo en la URL (https://api.tuapp.com/yave?token=…) y compáralo en tu servidor.
• Responde 2xx en menos de 15 segundos. Si necesitas procesar algo pesado, encólalo y responde de inmediato.
• No hay reintentos automáticos: una respuesta distinta de 2xx o un timeout marcan el paso como fallido en el historial de la automatización, desde donde un administrador puede volver a ejecutarlo.
• Haz tu endpoint idempotente (por ejemplo con lead.id y la etapa): la misma automatización puede volver a correr para un lead.