Webhooks

Al crear una instancia proporcionás un webhookUrl. El gateway envía un POST a esa URL cada vez que ocurre un evento relevante, con body JSON firmado con HMAC-SHA256.

Verificar firma

Cada request incluye el header x-gateway-signature. Siempre verificar antes de procesar.

javascript

const crypto = require('crypto')

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return expected === signature
}

python

import hmac, hashlib

def verify_signature(raw_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return expected == signature

Política de reintentos

El gateway reintenta 3 veces si tu endpoint no responde 2xx: delays de 1s, 5s, 30s. Tu endpoint debe responder rápidamente.

Evento: instance.connected / instance.disconnected

json

{
  "event": "instance.connected",
  "instanceName": "acme__soporte__main",
  "data": { "state": "open", "reason": null },
  "timestamp": "2026-03-15T10:30:00.000Z"
}

Evento: message.received

json

{
  "event": "message.received",
  "instanceName": "acme__soporte__main",
  "data": {
    "from": "5491112345678",
    "pushName": "Juan Pérez",
    "messageType": "conversation",
    "text": "Hola, necesito ayuda",
    "messageId": "AC3EADB76DB5BE4130602FBF2039604A",
    "timestamp": 1773596760
  },
  "timestamp": "2026-03-15T10:30:00.000Z"
}

text es null para mensajes con media (imagen, audio, etc.).
Solo se reenvían mensajes con fromMe: false (no los propios mensajes enviados).
messageType posibles: conversation, imageMessage, documentMessage, audioMessage, videoMessage.

Eventos disponibles

Evento	Cuándo
`message.received`	Mensaje entrante de un contacto
`instance.connected`	Sesión WhatsApp activa
`instance.disconnected`	Sesión caída o deslogueada