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.
- Abre Configuración → Desarrolladores → Webhooks.
- Haz clic en Nuevo webhook.
- 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. - En Eventos elige Todos los eventos o Eventos especificos y marca los que quieres.
- En Canales deja Todos los canales o limita el webhook a WhatsApp, Instagram, Facebook o Chat web.
- Haz clic en Crear webhook.
- Copia el Secret de firma que aparece: se muestra una sola vez y lo necesitas para verificar la firma.
- En el menú ⋯ del webhook elige Enviar prueba: Yolani manda un evento
test.pingy 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
| Evento | Se dispara cuando |
|---|---|
message.received | Un cliente te envía un mensaje (cualquier canal) |
message.sent | Sale un mensaje de tu cuenta (una persona, el agente IA o la API) |
conversation.created | Se abre una conversación nueva |
conversation.updated | Cambia el estado de una conversación |
conversation.closed | Una conversación se marca como resuelta |
conversation.bot.enabled | Se enciende el agente IA en una conversación |
conversation.bot.disabled | Se pausa el agente IA en una conversación |
conversation.stage_changed | Un cliente pasa a otra etapa de tu embudo |
contact.created | Alguien te escribe por primera vez, o das de alta un contacto en el panel o por la API |
contact.updated | Cambian los datos de un contacto (en el panel, por la API, o el nombre y correo que le dio a tu agente) |
appointment.created | Se agenda una cita (tu agente, el panel, tu enlace de reservas, Calendly o Google Calendar) |
appointment.rescheduled | Una cita cambia de horario o de agenda |
appointment.cancelled | Una cita se cancela |
test.ping | Prueba 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_changedy los de contactos.conversation.createdtambién lo trae cuando el cliente escribe primero; las conversaciones que abre tu cuenta (desde la bandeja, la API o una campaña) llegan conchannel: nully por eso pasan cualquier filtro. - Los eventos sin canal (
conversation.updated,conversation.closed, los del agente IA, los de citas ytest.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
| Header | Descripción |
|---|---|
X-Yolani-Event | Tipo de evento |
X-Yolani-Event-Id | Id único del evento. Es el mismo en todos los reintentos: úsalo para descartar duplicados |
X-Yolani-Signature | Firma HMAC SHA-256 del cuerpo, con el formato sha256=<hex> |
X-Yolani-Attempt | Número de intento, de 1 a 6 (no viene en test.ping) |
User-Agent | Yolani-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
- En n8n crea un workflow con un nodo Webhook (método POST).
- Copia la URL de producción del nodo y regístrala en Configuración → Desarrolladores → Webhooks → Nuevo webhook.
- Elige los eventos que necesitas (por ejemplo
message.received). - Para contestar desde n8n, agrega un nodo HTTP Request con
POST https://api.yolani.co/api/v1/conversations/{{ $json.body.data.conversation_id }}/messagesy tu API key en el headerAuthorization(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étodo | Endpoint | Qué hace | Permiso (scope) |
|---|---|---|---|
| POST | /api/v1/webhooks | Da de alta un webhook | webhooks:manage + el de lectura de cada evento |
| GET | /api/v1/webhooks | Lista los webhooks dados de alta por la API | webhooks:manage |
| DELETE | /api/v1/webhooks/:id | Da de baja uno de esos webhooks | webhooks:manage |
| GET | /api/v1/webhooks/samples?event=... | Hasta 3 ejemplos del evento con datos de tu cuenta | El de lectura del evento |
Alta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
url | string | Sí | URL que recibe los eventos (https:// y pública). También se acepta como target_url |
events | string[] | Sí | Eventos a recibir (la lista de arriba). Con uno solo puedes mandar event |
origen | string | No | Etiqueta 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/webhooksyDELETEsolo 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 responde404.- 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
409conSUBSCRIPTION_LIMIT. - Errores de validación (
400,VALIDATION_ERROR): faltaurl, 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.