Webhooks

Registra una URL tuya y te enviaremos un POST con cada evento que te interese.

Administrar webhooks

GET    /webhooks           # listar
POST   /webhooks           # crear
PUT    /webhooks/{id}      # actualizar (url, events, active)
DELETE /webhooks/{id}      # eliminar

POST /webhooks
{
  "url": "https://tu-sistema.com/webhooks/wsperu",
  "events": ["message.status", "message.received", "session.disconnected"]
}

Al crear, la respuesta incluye un secret — guárdalo para verificar la firma.

Eventos

Evento	Cuándo se dispara
message.sent	El mensaje salió hacia WhatsApp
message.status	Cambió el estado de entrega (delivered, read)
message.failed	El envío falló tras los reintentos
message.received	Tu línea recibió un mensaje entrante
session.connected	La línea se conectó
session.disconnected	La línea se desconectó
session.qr	Se generó un QR nuevo (útil para re-vincular)

Ejemplo de payload

{
  "event": "message.received",
  "sessionId": "665f...",
  "data": {
    "from": "51987654321@s.whatsapp.net",
    "messageId": "3EB0...",
    "timestamp": 1755011111,
    "type": "conversation",
    "text": "Hola, quisiera información sobre mi pedido"
  }
}

text trae el cuerpo del mensaje (o el caption si es imagen/video/documento); es null para media sin caption — los archivos entrantes no se descargan.

Verificar la firma (HMAC-SHA256)

Cada request incluye el header x-webhook-signature: el HMAC-SHA256 del body usando tu secret.

const crypto = require('crypto');

function esValido(body, firma, secret) {
  const esperada = crypto.createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperada));
}

Reintentos

Si tu endpoint no responde 2xx, reintentamos hasta 3 veces con backoff exponencial. Responde rápido (encola internamente si tu procesamiento es lento) — el timeout es de 10 segundos.