# 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.

Source: https://docs.whatsetter.com/es/developers/webhooks/

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

| 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 |

> **`message.received` llega a menudo**
Se envía por cada mensaje que un lead escribe a tus agentes. Suscríbete solo si tu servidor necesita cada mensaje.

> **Una etiqueta que pone el agente: `contact.label_added`**
No viene de una suscripción. Sale hacia las URL de webhook configuradas en **Traspaso y alertas** de un agente, para las etiquetas elegidas ahí. Mira [Los webhooks configurados en un agente](#los-webhooks-configurados-en-un-agente).

## Crear una suscripción

[POST /webhooks](/api-reference/operations/createwebhook/) 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**

```bash
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"}'
```

**JavaScript**

```js
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 ahora
```

**Python**

```python
import 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
```

```json
{
  "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](/api-reference/operations/listwebhooks/) 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

[`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/) 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**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
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());
```

**Python**

```python
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())
```

```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

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

```json
{
  "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

| 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`

| 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. |

> **`phone` no lleva `+`**
`contact.phone` es el número internacional **sin el `+`**: `212600000000`, no `+212600000000`. Compara solo con los dígitos, o añade tú el `+`. `contact.lead_id` te da el identificador de WhatsApp en bruto si prefieres ese.

> **`external_reference` dice de quién es el lead**
Cuando creas un lead con [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/), pasa tu propio identificador en `external_reference`. Lo guardamos y te lo devolvemos en cada evento de ese contacto.

Vale `null` para cualquier lead que no venga de ti: un CSV importado desde el dashboard, o alguien que escribió al agente por su cuenta. **Un `null` significa que el lead no existe de tu lado: ignóralo, no es un emparejamiento fallido.**

### `agent.disconnected`

```json
{
  "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`

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`.

```json
{
  "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`

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.

```json
{
  "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

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](/es/dashboard/notifications/).

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`

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](/es/dashboard/labels/).

```json
{
  "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

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.

**Node.js**

```js
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
// });
```

**Python**

```python
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
```

**PHP**

```php
<?php
function 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);
```

> **Verifica sobre el cuerpo en bruto**
Si tu framework parsea el JSON antes que tú (Express `json()`, Flask `request.json`), volver a serializar puede cambiar el orden de las claves o los espacios y romper la firma. Hashea siempre los bytes exactamente como los recibes.

## 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 /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.

## Gestionar las suscripciones

- [GET /webhooks](/api-reference/operations/listwebhooks/) lista tus suscripciones, sin el secreto.
- [`DELETE /webhooks/{id}`](/api-reference/operations/deletewebhook/) detiene las entregas de inmediato. Para cambiar la URL o los eventos, borra y vuelve a crear: obtienes un secreto nuevo.

## Relacionado

- [Inicio rápido](/es/developers/quickstart/)
- [Errores, límites e idempotencia](/es/developers/errors/)
- [Guía de Leads](/es/developers/guides/leads/)
- [Guía de Campañas](/es/developers/guides/campaigns/)
