Webhooks

Los webhooks te permiten recibir eventos en tiempo real — mensajes entrantes, confirmaciones de entrega, estado de dispositivos.

Crear un webhook

Panel → webhooks → formulario:

URL: la URL pública a la que haremos POST.
Device: opcional, limita el webhook a un solo dispositivo.
Format: Native (JSON), Twilio-compatible (form-encoded), o 3CX (JSON 3CX-style).
Eventos: marca los que quieres recibir.

Al crear obtienes un secret — guárdalo para verificar firmas.

Eventos disponibles

Evento	Cuándo se dispara
`sms:received`	Llega un SMS al celular
`sms:sent`	Se envió (confirmado por el carrier)
`sms:delivered`	Se entregó al destinatario (requiere `withDeliveryReport: true`)
`sms:failed`	Falló el envío
`mms:received`	Llega un MMS
`mms:downloaded`	MMS descargado con adjuntos
`mms:sent` / `mms:delivered` / `mms:failed`	Estados MMS
`whatsapp:received` / `whatsapp:sent` / `whatsapp:delivered` / `whatsapp:failed`	Eventos WhatsApp
`system:ping`	Heartbeat periódico del dispositivo
`device:online` / `device:offline`	Conexión/desconexión del celular

Verificar firmas

Cada webhook trae estos headers:

x-smsgw-event: sms:received
x-smsgw-signature: <hex HMAC-SHA256 del body>
x-smsgw-format: native | twilio | threecx

Verificación en Node.js:

import crypto from 'crypto';

function verify(req, secret) {
  const expected = crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return req.headers['x-smsgw-signature'] === expected;
}

Reintentos

Si tu endpoint responde con un código 5xx o tarda más de 30 segundos, reintentamos con backoff exponencial (hasta 5 intentos en ~30 min). Tu endpoint debe ser idempotente — usa messageId o externalId como clave.

Formato Native

{
  "event": "sms:received",
  "deviceId": "cm...",
  "data": {
    "messageId": "cm...",
    "from": "+521...",
    "to": "+521...",
    "body": "...",
    "mediaUrls": null,
    "tenantId": "cm..."
  },
  "at": "2026-04-24T..."
}

Formato Twilio

Form-encoded con campos From, To, Body, MessageSid, MessageStatus, NumMedia, MediaUrl0..N, ErrorMessage.

Formato 3CX

JSON con campos MessageType (SMS/MMS/WHATSAPP), MessageId, Status, From, To, Body, MediaUrls, ReceivedAt.