# Tutorial de webhooks

> De punta a punta — levanta un receptor local, expónlo con un túnel, pide a watsi que lo registre, recibe tu primer evento y verifica su firma.

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

En este recorrido levantas un receptor en tu máquina, lo expones con un túnel, pides que lo registren y recibes un `message.received` real escribiéndole a tu propio número.

> **Antes de empezar**

- Node.js 18 o más reciente.
- Un número de WhatsApp conectado a tu espacio de trabajo de watsi.
- Una herramienta de túnel, como [ngrok](https://ngrok.com) o [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).

### Escribe el receptor

Guarda esto como `server.mjs`. Verifica la firma cuando hay secreto, deduplica por entrega y responde de inmediato.

```javascript server.mjs
import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET = process.env.WATSI_WEBHOOK_SECRET // vacío hasta que te den uno
const seen = new Set()

function verifyWatsiSignature(rawBody, header, secret) {
  if (typeof header !== 'string' || !header.startsWith('sha256=')) return false
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  const received = header.slice('sha256='.length)
  if (received.length !== expected.length) return false
  return timingSafeEqual(Buffer.from(received), Buffer.from(expected))
}

const app = express()

app.post('/webhooks/watsi', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('x-watsi-signature')
  if (SECRET && !verifyWatsiSignature(req.body, signature, SECRET)) return res.sendStatus(401)

  const deliveryId = req.get('x-watsi-delivery-id')
  if (seen.has(deliveryId)) return res.sendStatus(200)
  seen.add(deliveryId)

  res.sendStatus(200)
  console.log(req.get('x-watsi-event'), deliveryId, signature ? 'firmado' : 'SIN FIRMA')
  console.log(JSON.parse(req.body.toString('utf8')))
})

app.listen(3000, () => console.log('Escuchando en http://localhost:3000/webhooks/watsi'))
```

```bash
npm install express
node server.mjs
```

### Exponlo con un túnel

```bash
ngrok http 3000
```

Copia la URL HTTPS que te da (por ejemplo `https://a1b2c3.ngrok.app`). Tu endpoint completo es esa URL más `/webhooks/watsi`.

### Pide que lo registren

Escribe a [support@watsi.ai](mailto:support@watsi.ai) desde la cuenta de tu espacio de trabajo con:

- La URL completa: `https://a1b2c3.ngrok.app/webhooks/watsi`.
- Los eventos: para esta prueba, `message.received` y `conversation.created`.
- Que te generen un secreto de firma.

Cuando te confirmen el registro y te compartan el secreto, reinicia el receptor con él:

```bash
WATSI_WEBHOOK_SECRET="…" node server.mjs
```

### Dispara un evento

Desde otro teléfono, mándale un WhatsApp a tu número de negocio. En la consola verás algo así:

```text
message.received 4f6c1e2a-9b3d-4a7e-8c15-2d9f0b7e6a31 firmado
{
  message_id: '0b8f6c2e-4a51-4d0e-9a57-2f1d8c3e7b90',
  conversation_id: '6d2a9e14-8f3b-4c7a-b1e5-90c4d7f2a318',
  customer_id: 'c41f7b8a-2e6d-4a93-8b05-1d7e9f3c6a24',
  content: 'Hola',
  content_type: 'text',
  provider: 'whatsapp',
  external_message_id: 'wamid.HBgN…',
  created_at: '2026-10-30T16:04:11.000Z'
}
```

Si es la primera vez que ese teléfono te escribe, antes llega un `conversation.created`.

### Prueba los reintentos

Detén el receptor (`Ctrl+C`), manda otro mensaje y vuelve a levantarlo antes de un minuto. El reintento llega con el **mismo** `X-Watsi-Delivery-Id`: así es como deduplicas.

### Pasa a producción

- Despliega el receptor en una URL HTTPS estable y pide que actualicen el endpoint registrado.
- Guarda el secreto en tu gestor de secretos.
- Cambia el `Set` en memoria por una tabla con índice único sobre el id de entrega.
- Encola el trabajo pesado y responde `200` de inmediato: tienes 30 segundos antes de que cuente como fallo.

## Si no llega nada

- **Ningún evento**: revisa que el túnel siga arriba y que la URL registrada sea exactamente la tuya, con la ruta. Las URLs de un túnel gratuito cambian cada vez que lo reinicias.
- **`401` en tu consola**: el secreto del receptor no es el de tu endpoint, o estás verificando un cuerpo ya parseado. Ve [Firma y verificación](/webhooks/signing).
- **Llega `SIN FIRMA`**: tu endpoint aún no tiene secreto; pídelo antes de pasar a producción.
- **Duplicados**: tu receptor tardó en responder o falló; deduplica por `X-Watsi-Delivery-Id`.
