Webhooks

Recibe en tu servidor, n8n, Make o Zapier los eventos de tu cuenta al momento: mensajes, conversaciones, contactos, citas y cambios de etapa. Cómo configurarlos en el panel o por la API, qué trae cada evento, cómo verificar la firma y cómo funcionan los reintentos.

Un webhook es un aviso que Yolani le manda a una URL tuya cada vez que pasa algo en tu cuenta: te escribe un cliente, se agenda una cita, alguien avanza en el embudo. Así tu sistema reacciona al momento sin estar preguntándole a la API cada minuto.

Los webhooks vienen desde el plan Profesional (también en Escala y Enterprise, y en Corporativo si ya lo tienes contratado). No necesitas una API key para recibirlos: los das de alta en el panel. Si tu sistema necesita darlos de alta solo, por ejemplo una plataforma de automatización como Zapier o Make, puede hacerlo por la API.

Configurar un webhook

Lo configura el dueño o un administrador de la cuenta.

  1. Abre Configuración → Desarrolladores → Webhooks.
  2. Haz clic en Nuevo webhook.
  3. Escribe un Nombre y la URL destino: la de tu servidor o la del nodo Webhook de n8n, Make o Zapier. Tiene que ser https:// y pública. La Descripcion (opcional) es para ti.
  4. En Eventos elige Todos los eventos o Eventos especificos y marca los que quieres.
  5. En Canales deja Todos los canales o limita el webhook a WhatsApp, Instagram, Facebook o Chat web.
  6. Haz clic en Crear webhook.
  7. Copia el Secret de firma que aparece: se muestra una sola vez y lo necesitas para verificar la firma.
  8. En el menú ⋯ del webhook elige Enviar prueba: Yolani manda un evento test.ping y te dice si llegó (Prueba entregada) o no (La prueba fallo), con el código HTTP que respondió tu servidor.

En la misma pantalla puedes pausar un webhook con su interruptor y, desde el menú ⋯, Editar, Rotar secret (genera uno nuevo y el anterior deja de valer) o Eliminar. Abajo, la tabla de entregas muestra cada envío con su evento, el número de intento, cuánto tardó tu servidor y su estado: Entregado, Reintento programado, Agotado o Vencido.

Eventos disponibles

EventoSe dispara cuando
message.receivedUn cliente te envía un mensaje (cualquier canal)
message.sentSale un mensaje de tu cuenta (una persona, el agente IA o la API)
conversation.createdSe abre una conversación nueva
conversation.updatedCambia el estado de una conversación
conversation.closedUna conversación se marca como resuelta
conversation.bot.enabledSe enciende el agente IA en una conversación
conversation.bot.disabledSe pausa el agente IA en una conversación
conversation.stage_changedUn cliente pasa a otra etapa de tu embudo
contact.createdAlguien te escribe por primera vez, o das de alta un contacto en el panel o por la API
contact.updatedCambian los datos de un contacto (en el panel, por la API, o el nombre y correo que le dio a tu agente)
appointment.createdSe agenda una cita (tu agente, el panel, tu enlace de reservas, Calendly o Google Calendar)
appointment.rescheduledUna cita cambia de horario o de agenda
appointment.cancelledUna cita se cancela
test.pingPrueba manual con Enviar prueba

La lista también está en la API: GET /api/v1/webhooks/event-types (con tu API key, si tu plan la incluye).

Contactos nuevos:

Los contactos que importas (CSV, historial de WhatsApp) no disparan contact.created. Cuando una persona escribe por primera vez, contact.created sale antes que conversation.created, pero el orden de llegada no está garantizado: relaciónalos por contact_id.

Filtro por canal

Cada webhook puede limitarse a uno o más canales: whatsapp, instagram, facebook y web_widget (chat web). Por ejemplo, mandas los mensajes de WhatsApp a un flujo de n8n y los de Instagram a otro.

  • Con Todos los canales el webhook recibe los eventos de cualquier canal.
  • El filtro aplica a los eventos que traen channel: los de mensajes, conversation.stage_changed y los de contactos. conversation.created también lo trae cuando el cliente escribe primero; las conversaciones que abre tu cuenta (desde la bandeja, la API o una campaña) llegan con channel: null y por eso pasan cualquier filtro.
  • Los eventos sin canal (conversation.updated, conversation.closed, los del agente IA, los de citas y test.ping) se entregan siempre.

Formato del evento

Cada evento llega como un POST con un JSON así:

{
  "event_id": "3fa4c7de-9f11-4c0a-9d3e-2b8f0a61c111",
  "event_type": "message.received",
  "occurred_at": "2026-07-14T15:03:22.481Z",
  "data": {
    "message_id": 15204,
    "conversation_id": 913,
    "contact_id": 481,
    "direction": "inbound",
    "channel": "whatsapp",
    "type": "text",
    "content_preview": "¿Tienen lugar para un tinte el sábado?",
    "has_media": false,
    "sent_by_bot": false,
    "created_at": "2026-07-14T15:03:22.000Z"
  }
}

content_preview trae hasta 500 caracteres del mensaje. message.sent llega con la misma forma y direction: "outbound".

Así viene data en los demás eventos:

// conversation.created
{ "conversation_id": 913, "contact_id": 481, "channel": "whatsapp" }

// conversation.updated
{ "conversation_id": 913, "status": "waiting" }

// conversation.closed
{ "conversation_id": 913, "contact_id": 481, "reason": "manual", "closed_by_user_id": 411 }

// conversation.bot.enabled
{ "conversation_id": 913, "assistant_id": 52 }

// conversation.bot.disabled
{ "conversation_id": 913, "reason": "La clienta pidió hablar con una asesora" }

En conversation.closed, reason es manual (la cerró una persona o la API; entonces closed_by_user_id es null), bulk o bulk_contacts (cierre masivo desde el panel) o auto_inactivity (se cerró sola por inactividad).

// contact.created
{
  "contact_id": 481,
  "name": "Lucía Pérez",
  "phone": "5215512345678",
  "email": null,
  "channel": "whatsapp",
  "instagram_id": null,
  "facebook_id": null,
  "tags": [],
  "created_at": "2026-10-06T18:02:11.000Z",
  "updated_at": "2026-10-06T18:02:11.000Z",
  "source": "conversation",
  "conversation_id": 913
}
// appointment.created
{
  "appointment_id": 8525,
  "status": "confirmed",
  "title": "Tinte y corte",
  "start_time": "2026-10-25T17:00:00.000Z",
  "end_time": "2026-10-25T18:30:00.000Z",
  "duration_minutes": 90,
  "resource_id": 3,
  "resource_name": "Karla",
  "service_id": 12,
  "service_name": "Tinte y corte",
  "contact_id": 481,
  "conversation_id": 913,
  "customer_name": "Lucía Pérez",
  "customer_phone": "5215512345678",
  "source": "agente",
  "google_event_id": null,
  "replaced_by_appointment_id": null
}
// conversation.stage_changed
{
  "conversation_id": 913,
  "contact_id": 481,
  "channel": "whatsapp",
  "pipeline_id": 2,
  "pipeline_name": "Ventas",
  "stage_id": 12,
  "stage_name": "Cita agendada",
  "previous_stage_id": 11,
  "previous_stage_name": "Interesada",
  "source": "ai",
  "actor_user_id": null
}

source dice quién lo hizo. En contactos: conversation, panel, api o agent; contact.updated trae además changed_fields. En etapas: manual, ai, system o pipeline_assignment. En citas: agente, panel, enlace, google, calendly, voz y otros; puede venir null.

Citas: agenda, servicio y reagendados:

resource_id y resource_name son la agenda de la cita (por ejemplo, una estilista o un médico); service_id y service_name, el servicio. Si la cita no tiene servicio vienen null. Cuando reagendas desde el panel, appointment.rescheduled trae la misma appointment_id con el horario nuevo. Cuando la reagenda tu agente, recibes appointment.created de la cita nueva y appointment.rescheduled de la anterior, con su horario anterior, status: "rescheduled" y replaced_by_appointment_id igual a la appointment_id de la nueva: da de baja la primera y guarda la segunda. Cancelar una cita, desde donde sea, manda appointment.cancelled; si la vuelves a activar, llega otra vez como appointment.created con la misma appointment_id. Marcarla como completada o como "no asistió" no manda aviso.

Headers

HeaderDescripción
X-Yolani-EventTipo de evento
X-Yolani-Event-IdId único del evento. Es el mismo en todos los reintentos: úsalo para descartar duplicados
X-Yolani-SignatureFirma HMAC SHA-256 del cuerpo, con el formato sha256=<hex>
X-Yolani-AttemptNúmero de intento, de 1 a 6 (no viene en test.ping)
User-AgentYolani-Webhooks/1.0

Verificar la firma

Calcula el HMAC SHA-256 del cuerpo tal como llegó (sin parsearlo ni volverlo a convertir en JSON) con tu secret, y compáralo con X-Yolani-Signature:

// Node.js con Express: lee el cuerpo crudo en esta ruta
const crypto = require('crypto');
const express = require('express');
const app = express();

function verifyYolaniSignature(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const received = Buffer.from(signatureHeader || '');
  const wanted = Buffer.from(expected);
  return received.length === wanted.length && crypto.timingSafeEqual(received, wanted);
}

app.post('/webhooks/yolani', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyYolaniSignature(
    req.body,
    req.get('X-Yolani-Signature'),
    process.env.YOLANI_WEBHOOK_SECRET,
  );
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // responde ya y procesa después
  const event = JSON.parse(req.body.toString('utf8'));
  // ... tu lógica con event.event_type y event.data
});
import hmac, hashlib

def verify_yolani_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header or "", expected)

Reintentos

Tu servidor tiene 8 segundos para responder con un código 2xx. Cualquier otra cosa cuenta como fallo: otro código, que tarde más, o una redirección (Yolani no sigue redirecciones; registra la URL final).

Si falla, Yolani lo reintenta con el mismo event_id: a los 30 segundos, 2 minutos, 10 minutos, 1 hora y 6 horas. Son 6 intentos en total. Si el sexto también falla, el evento se da por perdido y te llega un aviso en el panel: Webhook fallando repetidamente. Si pausas o eliminas el webhook, sus reintentos pendientes ya no se envían. Un reintento que no pudo salir en 24 horas (por ejemplo, durante una falla de nuestro lado) ya no se envía: queda Vencido, para que tu sistema no reciba eventos de hace días.

Responde rápido:

Responde 200 de inmediato y procesa el evento después. Usa X-Yolani-Event-Id para descartar los que te lleguen repetidos.

Uso con n8n

  1. En n8n crea un workflow con un nodo Webhook (método POST).
  2. Copia la URL de producción del nodo y regístrala en Configuración → Desarrolladores → Webhooks → Nuevo webhook.
  3. Elige los eventos que necesitas (por ejemplo message.received).
  4. Para contestar desde n8n, agrega un nodo HTTP Request con POST https://api.yolani.co/api/v1/conversations/{{ $json.body.data.conversation_id }}/messages y tu API key en el header Authorization (ver Mensajes). Contestar necesita un plan con API.

Dar de alta webhooks desde la API (REST Hook)

Además del panel, tu sistema puede dar de alta y de baja sus propios webhooks con una API key que tenga el permiso webhooks:manage (Webhooks en el panel). Sirve para cualquier integración que dé de alta su webhook al encender un flujo y lo borre al apagarlo (el patrón "REST Hook" de las plataformas de automatización). Necesita un plan con API.

MétodoEndpointQué hacePermiso (scope)
POST/api/v1/webhooksDa de alta un webhookwebhooks:manage + el de lectura de cada evento
GET/api/v1/webhooksLista los webhooks dados de alta por la APIwebhooks:manage
DELETE/api/v1/webhooks/:idDa de baja uno de esos webhookswebhooks:manage
GET/api/v1/webhooks/samples?event=...Hasta 3 ejemplos del evento con datos de tu cuentaEl de lectura del evento

Alta

CampoTipoRequeridoDescripción
urlstringSíURL que recibe los eventos (https:// y pública). También se acepta como target_url
eventsstring[]SíEventos a recibir (la lista de arriba). Con uno solo puedes mandar event
origenstringNoEtiqueta de quién lo da de alta: zapier, make o api (cualquier otro valor o ninguno queda como api). Sale en el nombre del webhook

Cada evento pide además el permiso de leer lo que trae: los contact.* piden contacts:read; los demás (mensajes, conversaciones, citas, etapas), conversations:read. Si a la key le falta, responde 403 con INSUFFICIENT_SCOPE.

curl -X POST https://api.yolani.co/api/v1/webhooks \
  -H "Authorization: Bearer yol_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tu-servidor.com/yolani", "events": ["contact.created", "appointment.created"]}'

Respuesta (201):

{
  "success": true,
  "data": {
    "id": 57,
    "url": "https://tu-servidor.com/yolani",
    "events": ["contact.created", "appointment.created"],
    "origen": "api",
    "enabled": true,
    "created_at": "2026-10-28T17:20:41.000Z",
    "secret": "whk_3c9f0e..."
  }
}

secret sirve para verificar la firma y solo viene en esta respuesta. El webhook recibe eventos de todos los canales, con el mismo formato, firma y reintentos que uno del panel.

Baja y lista

curl -X DELETE https://api.yolani.co/api/v1/webhooks/57 \
  -H "Authorization: Bearer yol_TU_TOKEN"

Responde {"success": true, "data": {"id": 57, "deleted": true}}.

  • GET /api/v1/webhooks y DELETE solo ven los webhooks que dio de alta una API key de tu cuenta. Los que creaste en el panel no aparecen ahí, y borrarlos por la API responde 404.
  • Los que da de alta la API sí aparecen en Configuración → Desarrolladores → Webhooks, con un nombre como "API: contact.created".
  • Si revocas la API key (o vence), los webhooks que dio de alta dejan de recibir eventos al momento, reintentos incluidos.
  • Hay un tope de 100 webhooks dados de alta por la API en cada cuenta; al llegar, el alta responde 409 con SUBSCRIPTION_LIMIT.
  • Errores de validación (400, VALIDATION_ERROR): falta url, la URL no es válida, o un evento no existe.

Ejemplos de un evento

GET /api/v1/webhooks/samples?event=contact.created devuelve hasta 3 eventos de ejemplo armados con datos reales de tu cuenta y con la misma forma que el evento de verdad, para probar un flujo antes de que llegue uno. Si todavía no tienes datos de ese tipo, devuelve un ejemplo fijo. Cada ejemplo trae "sample": true y su event_id empieza con muestra:.

Funciona con contact.created, contact.updated, appointment.created, appointment.rescheduled, appointment.cancelled, conversation.stage_changed y message.received; con otro evento responde 400.

Webhooks entrantes:

Hoy no se pueden configurar webhooks entrantes desde el panel. Para que tu sistema cree o actualice contactos en Yolani usa POST /api/v1/contacts, y para mandar mensajes, la API.