Integraciones
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.
Los eventos
Sección titulada «Los eventos»| 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 |
Crear una suscripción
Sección titulada «Crear una suscripción»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.
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"}'const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', { method: 'POST', headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://tu-servidor.com/webhooks/whatsetter', events: ['contact.qualified', 'contact.not_qualified'], description: 'Sync CRM', }),});const { data } = await res.json();console.log(data.secret); // whsec_… se muestra una sola vez, guárdalo ahoraimport os, requests
r = requests.post( "https://app.whatsetter.com/api/v1/webhooks", headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"}, json={ "url": "https://tu-servidor.com/webhooks/whatsetter", "events": ["contact.qualified", "contact.not_qualified"], "description": "Sync CRM", },)print(r.json()["data"]["secret"]) # whsec_… se muestra una sola vez, guárdalo ahora{ "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. |
Probar la entrega
Sección titulada «Probar la entrega»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.
curl -X POST https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test \ -H "Authorization: Bearer $WHATSETTER_API_KEY"const res = await fetch('https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test', { method: 'POST', headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },});console.log(await res.json());import os, requests
r = requests.post( "https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test", headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},)print(r.json()){ "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.
Lo que recibes
Sección titulada «Lo que recibes»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" }}Campos del sobre
Sección titulada «Campos del sobre»| 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. |
contact.qualified y contact.not_qualified
Sección titulada «contact.qualified y contact.not_qualified»| 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. |
agent.disconnected
Sección titulada «agent.disconnected»{ "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.
booking.created
Sección titulada «booking.created»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.
message.received
Sección titulada «message.received»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.
Los webhooks configurados en un agente
Sección titulada «Los webhooks configurados en un agente»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.
contact.label_added
Sección titulada «contact.label_added»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.
Verificar la firma
Sección titulada «Verificar la firma»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/jsonUser-Agent: Whatsetter-Webhooks/1.0X-Whatsetter-Event: contact.qualifiedX-Whatsetter-Delivery: evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013X-Whatsetter-Timestamp: 2026-09-15T09:10:12.517ZX-Whatsetter-Api-Version: 2026-06-01X-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// });import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool: expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, header or "")
# Flask: usa request.get_data(), no request.json, para conservar el cuerpo en bruto# @app.post("/webhooks/whatsetter")# def whatsetter_webhook():# if not verify(request.get_data(), request.headers.get("X-Whatsetter-Signature", ""), os.environ["WHATSETTER_WEBHOOK_SECRET"]):# return "", 401# event = request.get_json()# return "", 200<?phpfunction verify(string $rawBody, string $header, string $secret): bool{ $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret); return hash_equals($expected, $header);}
$rawBody = file_get_contents('php://input');$header = $_SERVER['HTTP_X_WHATSETTER_SIGNATURE'] ?? '';
if (!verify($rawBody, $header, getenv('WHATSETTER_WEBHOOK_SECRET'))) { http_response_code(401); exit;}$event = json_decode($rawBody, true);http_response_code(200);Reglas de entrega
Sección titulada «Reglas de entrega»- 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 /leadssi sospechas un hueco. - La petición caduca a los 10 segundos. Responde
2xxde 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_atylast_delivery_statusen la suscripción te dicen cómo fue la última entrega.
Gestionar las suscripciones
Sección titulada «Gestionar las suscripciones»- 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.