Ir al contenido
Dashboard

Webhooks firmados

Recibe los eventos de WhatSetter en tu servidor en cuanto suceden, verifica la firma HMAC-SHA256 en Node.js, Python o PHP, y prueba tu endpoint.

En lugar de consultar la API en bucle, deja que WhatSetter te empuje los eventos a tu servidor en cuanto suceden. Cada entrega va firmada, así que puedes estar seguro de que viene de nosotros.

Evento Se dispara cuando Estado
contact.qualified El agente califica un lead (según los criterios de tu prompt) Activo
contact.not_qualified El agente descarta un lead Activo
agent.disconnected Un número de WhatsApp se desconecta Activo
booking.created Tu agente agenda una cita en la conversación Activo
message.received Un lead escribe a uno de tus agentes Activo

POST /webhooks necesita el scope webhooks:manage. La URL debe ser una dirección HTTPS pública: se rechazan localhost, las redes privadas y las direcciones reservadas.

Terminal window
curl -X POST https://app.whatsetter.com/api/v1/webhooks \
-H "Authorization: Bearer $WHATSETTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://tu-servidor.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"],"description":"Sync CRM"}'
{
"data": {
"id": "66f1c0ffee00000000000abc",
"url": "https://tu-servidor.com/webhooks/whatsetter",
"events": ["contact.qualified", "contact.not_qualified"],
"active": true,
"description": "Sync CRM",
"secret_prefix": "whsec_3f9a",
"secret": "whsec_3f9a…",
"last_delivery_at": null,
"last_delivery_status": null,
"created_at": "2026-09-19T10:00:00.000Z"
}
}

La respuesta contiene el secreto de firma (whsec_…). Solo se muestra aquí: guárdalo de inmediato. Las llamadas posteriores a GET /webhooks solo devuelven secret_prefix.

Errores que importan:

HTTP code Por qué
422 validation_error url ausente o sin HTTPS, events vacío o desconocido, description de más de 255 caracteres.
429 quota_exceeded El espacio ya tiene 10 suscripciones. Borra una primero.

POST /webhooks/{id}/test envía de inmediato un evento de ejemplo firmado a la URL de la suscripción e informa de cómo respondió tu endpoint. El ejemplo usa el primer evento de la suscripción y lleva "is_test": true.

Terminal window
curl -X POST https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test \
-H "Authorization: Bearer $WHATSETTER_API_KEY"
{
"data": {
"delivered": true,
"endpoint_status": 200,
"error": null,
"event_id": "evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013"
}
}

delivered es false cuando tu endpoint respondió algo distinto de un estado 2xx (mira endpoint_status) o no se pudo alcanzar en 10 segundos (mira error). Un 404 not_found significa que el id de suscripción es desconocido o pertenece a otro espacio.

Cada entrega comparte el mismo sobre. Los campos propios del evento van al lado de los del sobre, no anidados bajo una clave payload.

{
"event_type": "contact.qualified",
"event_id": "evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013",
"api_version": "2026-06-01",
"occurred_at": "2026-09-15T09:10:12.517Z",
"team_id": "6b0c1d2e3f405162738a",
"is_test": false,
"campaign": {
"id": "6b0c1d2e3f4051627abc",
"slug": "acme-morocco-1-ab12",
"name": "Alex"
},
"contact": {
"id": "6b0c1d2e3f4051627def",
"lead_id": "212600000000@c.us",
"name": "Sam",
"phone": "212600000000",
"classification": "qualified",
"ai_reasoning": "Busca un SUV, presupuesto confirmado, quiere que le llamen.",
"conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=212600000000%40c.us",
"external_reference": "your-crm-id-12345"
}
}
Campo Detalle
event_type Uno de los eventos de arriba.
event_id Único por entrega. Úsalo para deduplicar.
api_version Actualmente 2026-06-01.
occurred_at ISO 8601, en UTC.
team_id El espacio de WhatSetter al que pertenece el evento.
is_test true si se envió desde POST /webhooks/{id}/test.
Campo Detalle
campaign.id Identificador interno de la campaña.
campaign.slug Identificador estable y legible de la campaña.
campaign.name El nombre visible del agente.
contact.id Identificador interno del lead, el mismo id que en GET /leads.
contact.lead_id Identificador de WhatsApp en bruto, por ejemplo 212600000000@c.us.
contact.name Nombre detectado por el agente, puede ser null.
contact.phone Solo dígitos, mira el aviso de abajo.
contact.classification El veredicto del agente.
contact.ai_reasoning Por qué el agente lo decidió así, en texto claro.
contact.conversation_url Enlace directo a la conversación en WhatSetter.
contact.external_reference Tu propio identificador, mira el consejo de abajo.
{
"event_type": "agent.disconnected",
"event_id": "evt_…",
"api_version": "2026-06-01",
"occurred_at": "2026-09-14T13:00:09.250Z",
"team_id": "6b0c1d2e3f405162738a",
"is_test": false,
"agent": {
"name": "Alex",
"phone": "212611111111@c.us",
"campaign_id": "acme-morocco-1-ab12",
"campaign_name": "Acme Morocco 1",
"session_status": "disconnected",
"disconnected_at": "2026-09-14T12:54:00.000Z"
}
}

Se envía una sola vez, al detectar el incidente. Los recordatorios de reconexión no lo reenvían.

Se envía cuando tu agente agenda una cita en la conversación (Reservar en la conversación activado). Una cita que el lead reserva por su cuenta con un enlace no se notifica. campaign y contact son los mismos bloques que en contact.qualified.

{
"event_type": "booking.created",
"event_id": "evt_…",
"api_version": "2026-06-01",
"occurred_at": "2026-10-18T14:02:41.118Z",
"team_id": "6b0c1d2e3f405162738a",
"is_test": false,
"campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-berlin-1-cd34", "name": "Julia" },
"contact": {
"id": "6b0c1d2e3f4051627def",
"lead_id": "491701234567@c.us",
"name": "Max",
"phone": "491701234567",
"conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=491701234567%40c.us",
"external_reference": "your-crm-id-12345"
},
"booking": {
"id": "6b0c1d2e3f4051627fed",
"start": "2026-10-20T08:00:00.000Z",
"end": "2026-10-20T08:30:00.000Z",
"timezone": "Europe/Berlin",
"status": "confirmed",
"provider": "cal_com",
"attendee_email": "max@example.com",
"attendee_phone": "+491701234567",
"meeting_url": "https://app.cal.com/video/abc123",
"location": null
}
}
Campo Notas
booking.id La cita en WhatSetter.
booking.start, booking.end ISO 8601, UTC.
booking.timezone La zona horaria en la que se propusieron los horarios.
booking.status confirmed, o pending cuando tu tipo de evento te pide aceptar la cita.
booking.provider cal_com, calendly o ghl.
booking.attendee_email, booking.attendee_phone Con qué se reservó la cita, puede ser null. Aquí el teléfono lleva su +.
booking.meeting_url El enlace de videollamada, cuando tu herramienta de calendario lo da.
booking.location El lugar, para una cita presencial o por teléfono.

Llega después de la respuesta de tu agente al lead, normalmente en menos de un minuto.

Se envía por cada mensaje que un lead escribe a uno de tus agentes en un chat privado (no en grupos), una vez que tu agente lo ha leído. También se envía cuando alguien de tu equipo ha tomado la conversación. No se envía para un número que bloqueaste.

{
"event_type": "message.received",
"event_id": "evt_…",
"api_version": "2026-06-01",
"occurred_at": "2026-10-18T14:01:07.540Z",
"team_id": "6b0c1d2e3f405162738a",
"is_test": false,
"campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-berlin-1-cd34", "name": "Julia" },
"contact": {
"id": "6b0c1d2e3f4051627def",
"lead_id": "491701234567@c.us",
"name": "Max",
"phone": "491701234567",
"conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=491701234567%40c.us",
"external_reference": null
},
"message": {
"id": "false_491701234567@c.us_3EB0A1B2C3D4E5F6",
"text": "Hallo, ich hätte eine Frage zu Dubai.",
"has_media": false,
"received_at": "2026-10-18T14:00:55.000Z"
}
}
Campo Notas
message.id El identificador de WhatsApp del mensaje.
message.text Lo que escribió el lead, hasta 4.096 caracteres. null para una foto o una nota de voz sin texto.
message.has_media true cuando el mensaje contiene una foto, un documento o una nota de voz.
message.received_at Cuándo lo recibió WhatsApp, ISO 8601, UTC.

contact.phone es null cuando WhatsApp oculta el número del lead. contact.id puede ser null en el primer mensaje de un lead. Llega después de la respuesta de tu agente, normalmente en menos de un minuto.

Además de tus suscripciones, cada agente puede llamar hasta 3 URL de webhook propias. Se configuran en el dashboard, no por la API: Ajustes del agente, Traspaso y alertas, Por webhook (avanzado), con un Secreto de firma opcional. Mira Notificaciones y alertas.

Esas URL reciben los leads cualificados o no cualificados que el agente está configurado para avisar, y contact.label_added. contact.label_added solo existe ahí: POST /webhooks no lo acepta.

Se envía cuando el agente pone una de sus etiquetas en un lead, para las etiquetas elegidas en Y cuando el agente pone la etiqueta en Traspaso y alertas. Mira Etiquetas del agente.

{
"event_type": "contact.label_added",
"event_id": "evt_4b1f0c9a2d7e4f3a8b6c5d0e1f2a3b4c",
"api_version": "2026-06-01",
"occurred_at": "2026-10-19T09:14:03.201Z",
"team_id": "6b0c1d2e3f405162738a",
"campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-madrid-1-cd34", "name": "Julia" },
"contact": {
"id": "6b0c1d2e3f4051627def",
"lead_id": "34612345678@c.us",
"name": "Lucía",
"phone": "+34612345678",
"conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=34612345678%40c.us"
},
"label": {
"id": "t3k9x2ab",
"label": "Presupuesto validado",
"posed_by": "ai",
"reason": "El lead da un presupuesto de 5.000 euros, que encaja con la oferta."
},
"is_test": false
}
Campo Notas
campaign.id, campaign.slug, campaign.name El agente, como en contact.qualified.
contact.id Id interno del lead, el mismo id que en GET /leads.
contact.lead_id Id de WhatsApp en bruto.
contact.name Nombre del lead, una cadena vacía si no se conoce.
contact.phone Con su + aquí, a diferencia de contact.qualified.
contact.conversation_url Enlace directo a la conversación en WhatSetter.
label.id El id de la etiqueta en los ajustes del agente. No cambia cuando se renombra la etiqueta.
label.label El nombre de la etiqueta.
label.posed_by ai cuando la IA la leyó en la conversación, o el hecho que la puso: fact:first_message, fact:booked o fact:no_reply.
label.reason Por qué: la frase de la IA, o el hecho dicho en una frase, en el idioma de las notificaciones del agente. Puede estar vacío.

Este evento no tiene classification ni external_reference. Se envía:

  • solo para un lead activo en las últimas 24 horas. Al activar las etiquetas, el agente relee una vez las conversaciones más antiguas sin enviar nada;
  • una vez cada vez que el agente pone la etiqueta, nunca por una etiqueta que puso una persona;
  • nunca mientras las etiquetas del agente están desactivadas.

Las cabeceras son las de abajo, con X-Whatsetter-Event: contact.label_added. X-Whatsetter-Signature solo está si el agente tiene un Secreto de firma, y se calcula con ese secreto, no con el whsec_… de una suscripción. Cada llamada se intenta una sola vez, espera 6 segundos como máximo, no sigue redirecciones y solo sale hacia una dirección https:// pública.

Cada entrega va firmada con HMAC-SHA256 del cuerpo en bruto de la petición, usando el secreto de tu suscripción. Las cabeceras que recibes:

Content-Type: application/json
User-Agent: Whatsetter-Webhooks/1.0
X-Whatsetter-Event: contact.qualified
X-Whatsetter-Delivery: evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013
X-Whatsetter-Timestamp: 2026-09-15T09:10:12.517Z
X-Whatsetter-Api-Version: 2026-06-01
X-Whatsetter-Signature: sha256=<hex>

X-Whatsetter-Delivery repite el event_id del sobre, y X-Whatsetter-Timestamp su occurred_at. Calcula sha256= + el HMAC hexadecimal del cuerpo en bruto y compáralo con X-Whatsetter-Signature en tiempo constante.

import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(rawBody) // el cuerpo EN BRUTO, antes de cualquier JSON.parse
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(header || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express: conserva el cuerpo en bruto en esta ruta
// app.post('/webhooks/whatsetter', express.raw({ type: 'application/json' }), (req, res) => {
// if (!verify(req.body, req.get('X-Whatsetter-Signature'), process.env.WHATSETTER_WEBHOOK_SECRET)) {
// return res.status(401).end();
// }
// const event = JSON.parse(req.body);
// res.status(200).end(); // responde rápido, procesa en asíncrono
// });
  • Un solo intento por evento. Si tu endpoint está caído o responde un error, el evento no se reintenta y se pierde. Mantén el endpoint disponible, y reconcilia con GET /leads si sospechas un hueco.
  • La petición caduca a los 10 segundos. Responde 2xx de inmediato y haz tu procesamiento de forma asíncrona; un timeout cuenta como fallo.
  • Deduplica igualmente por event_id. No cuesta nada y te protege si más adelante se añaden reintentos.
  • Un evento se reparte a cada suscripción activa que lo incluya, hasta 10 suscripciones por espacio. Dos suscripciones a la misma URL reciben cada una su copia.
  • last_delivery_at y last_delivery_status en la suscripción te dicen cómo fue la última entrega.
  • GET /webhooks lista tus suscripciones, sin el secreto.
  • DELETE /webhooks/{id} detiene las entregas de inmediato. Para cambiar la URL o los eventos, borra y vuelve a crear: obtienes un secreto nuevo.