Tutorial completo

Este recorrido muestra un flujo práctico de desarrollo local: levante un manejador, expóngalo con un túnel, registre una suscripción y luego verifique la entrega firmada que reciba.

Paso 1

Inicie un manejador local

Cree un pequeño endpoint HTTP que almacene el cuerpo de la solicitud sin procesar y verifique el encabezado X-Watsi-Signature antes de analizar el JSON.

import crypto from 'crypto'
import http from 'http'

const secret = process.env.WATSI_WEBHOOK_SECRET ?? ''

function verifySignature(rawBody, signature) {
  if (!signature) return false
  const computed = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const expectedBuf = Buffer.from(String(signature), 'utf8')
  const computedBuf = Buffer.from(computed, 'utf8')
  return expectedBuf.length === computedBuf.length && crypto.timingSafeEqual(expectedBuf, computedBuf)
}

http.createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhooks/watsi') {
    res.writeHead(404)
    res.end()
    return
  }

  const chunks = []
  req.on('data', (chunk) => chunks.push(chunk))
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks)
    const signature = req.headers['x-watsi-signature']

    if (!verifySignature(rawBody, signature)) {
      res.writeHead(401)
      res.end('Invalid signature')
      return
    }

    const event = JSON.parse(rawBody.toString('utf8'))
    console.log('verified event', event.type, event.id)
    res.writeHead(200)
    res.end('OK')
  })
}).listen(4000)

Paso 2

Expóngalo sobre HTTPS

Use una herramienta de túnel como ngrok para que watsi pueda alcanzar su máquina local.

ngrok http 4000

Paso 3

Registre una suscripción

Cree una suscripción que apunte a la URL HTTPS de su túnel. La superficie REST exacta puede evolucionar, pero el contrato de integración es: URL de destino, lista de eventos y un secreto de firma almacenado por su aplicación.

curl -X POST https://api.watsi.ai/api/v1/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://YOUR_TUNNEL_HOST/webhooks/watsi",
    "events": ["message.received", "message.status"]
  }'

Paso 4

Capture el secreto de firma

Almacene el secreto de firma devuelto en su entorno antes de enviar tráfico real al manejador.

export WATSI_WEBHOOK_SECRET='replace-with-your-secret'
node webhook-server.mjs

Paso 5

Active una entrega de prueba

Envíe un mensaje entrante real o use su superficie de gestión de suscripciones para activar un evento de prueba. Sus registros deberían mostrar un tipo de evento verificado y un id de evento.

verified event message.received evt_01HXYZ123456789

Lista de verificación para producción

Responda rápidamente con 2xx y realice el trabajo pesado de forma asíncrona.
Use event.id o X-Watsi-Delivery-Id para la deduplicación.
Conserve registros con el tipo de evento, el id de entrega y el id del espacio de trabajo.
Trate los tipos de eventos futuros desconocidos como no fatales.
Mantenga el secreto de firma en un gestor de secretos, no en el código fuente.