# Webhooks

> Cómo watsi entrega eventos a tu endpoint HTTPS — registro, encabezados, cuerpo, firma, reintentos con sus tiempos reales y qué pasa cuando tu endpoint no responde.

Source: https://docs.watsi.ai/webhooks

Con los webhooks, watsi te avisa en cuanto algo pasa —llega un mensaje, se asigna una conversación, se agenda una cita— con un `POST` a tu endpoint. No tienes que consultar la API para enterarte.

## Registro

Los endpoints los registra el **equipo de watsi**; todavía no hay una API ni una pantalla para hacerlo tú. Escribe a [support@watsi.ai](mailto:support@watsi.ai) con:

- La **URL HTTPS** de tu endpoint (sólo HTTPS).
- Los **eventos** que quieres recibir (ve el [catálogo](/webhooks/events)).
- Que te generen un **secreto de firma**, para que puedas comprobar que cada entrega viene de watsi.

Puedes tener varios endpoints por espacio de trabajo, cada uno con sus eventos. Para cambiar la URL, los eventos o pausar un endpoint, escribe al mismo correo. El [tutorial](/webhooks/tutorial) recorre todo el proceso.

## Qué recibes

Cada entrega es un `POST` con `Content-Type: application/json`. **El cuerpo es el evento**, plano y sin sobre: no trae el tipo de evento ni un id de entrega; esos van en los encabezados.

```http
POST /webhooks/watsi HTTP/1.1
Content-Type: application/json
X-Watsi-Event: message.received
X-Watsi-Delivery-Id: 4f6c1e2a-9b3d-4a7e-8c15-2d9f0b7e6a31
X-Watsi-Signature: sha256=6b1f0c…

{"message_id":"0b8f6c2e-…","conversation_id":"6d2a9e14-…","customer_id":"c41f7b8a-…","content":"Hola, ¿tienen citas para mañana?","content_type":"text","provider":"whatsapp","created_at":"2026-10-30T16:04:11.000Z"}
```

- `X-Watsi-Event` (string)
  El tipo de evento, como `message.received`. Enruta con él: el cuerpo no lo repite.
- `X-Watsi-Delivery-Id` (string)
  Id único de la entrega. Se mantiene igual en cada reintento de la misma entrega: deduplica con él.
- `X-Watsi-Signature` (string)
  `sha256=` seguido del HMAC-SHA256 en hexadecimal del cuerpo exacto, con el secreto de tu endpoint.
  Sólo viene si tu endpoint tiene secreto. [Cómo verificarla](/webhooks/signing).

Los campos de cada evento, con ejemplos reales, están en el [catálogo de eventos](/webhooks/events). Ten en cuenta que no todos los eventos traen una marca de tiempo; si necesitas una, usa la hora en que recibes la entrega.

> **Warning**

Si tus entregas llegan **sin** `X-Watsi-Signature`, tu endpoint todavía no tiene secreto de firma y cualquiera que conozca la URL podría imitarlas. Pide el secreto antes de usar el endpoint en producción.

## Entrega y reintentos

Tu endpoint confirma una entrega respondiendo **cualquier `2xx` en menos de 30 segundos**. Cualquier otra cosa —un `3xx`, `4xx` o `5xx`, un error de red o pasar de 30 segundos— cuenta como fallo, y watsi reintenta:

| Intento | Cuándo                                       |
| ------- | -------------------------------------------- |
| 1       | Poco después del evento                      |
| 2       | Unos **1 minuto** después de que falle el 1  |
| 3       | Unos **2 minutos** después de que falle el 2 |
| 4       | Unos **4 minutos** después de que falle el 3 |

Cada espera lleva hasta un 10 % extra al azar. Si el cuarto intento también falla, la entrega queda como **no entregada** y watsi deja de intentarlo: a partir del primer fallo tienes unos 7 minutos para recuperar tu endpoint. Si se te cayó más tiempo, escríbenos con el rango de horas y los eventos afectados.

watsi guarda el código de estado y los primeros 4 KB de tu respuesta de cada intento, para diagnosticar contigo una entrega que no llegó.

## Garantías

- **Al menos una vez.** La misma entrega puede llegar más de una vez (por ejemplo, si tu endpoint procesó pero respondió tarde). Deduplica con `X-Watsi-Delivery-Id`.
- **Sin orden.** Dos eventos pueden llegarte en otro orden del que ocurrieron, sobre todo si uno se reintentó.
- **Responde rápido.** Guarda el evento, responde `200` y procésalo después. Un endpoint que tarda en responder acaba recibiendo duplicados.

- [Catálogo de eventos](/webhooks/events)
    Cada evento con su cuerpo.
- [Firma](/webhooks/signing)
    Verifica cada entrega.
- [Tutorial](/webhooks/tutorial)
    Tu primer evento, de punta a punta.
