Webhooks: recibir eventos de la cuenta

Registre el destino

El titular con correo confirmado accede a Cuenta → API e integraciones → Webhooks → Añadir webhook. Indique nombre, URL y eventos; defina el límite de saldo bajo cuando corresponda. Hay hasta 10 destinos activos por cuenta. La URL debe usar HTTPS en el puerto 443 con IPv4 pública, sin credenciales, parámetros ni fragmentos. Guarde el secreto que se muestra una vez, configúrelo en el receptor y use Enviar prueba.

Elija los eventos

Los eventos usan POST y application/json con identificadores y datos mínimos. No envían mensajes completos de tickets ni credenciales. Las respuestas antiguas e instalaciones ya terminadas no se reenvían al registrar un destino.

Permisos y detalles

server.installation.completed

server_key

ticket.reply.created

ticket_id, reply_id, from_support

balance.low

balance, threshold y currency al cruzar por debajo del límite; no hay aviso retroactivo si el saldo ya era bajo.

JSON

{
  "id": "00000000-0000-4000-8000-000000000001",
  "type": "ticket.reply.created",
  "created_at": "2026-10-17T12:00:00Z",
  "account_id": 123,
  "data": {
    "ticket_id": 456,
    "reply_id": 789,
    "from_support": true
  }
}

Valide la firma

WordPane-Signature usa t=TIMESTAMP,v1=FIRMA. Calcule HMAC-SHA256 sobre timestamp + "." + cuerpo original, compare en tiempo constante y rechace diferencias superiores a 5 minutos. WordPane-Event-Id debe coincidir con id en el cuerpo. El ejemplo usa módulos nativos de Node.js.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWordPane(rawBody, headers, secret, now = Date.now()) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(
    headers['wordpane-signature'] ?? ''
  );
  if (!Buffer.isBuffer(rawBody) || !match || !secret) return null;
  if (Math.abs(now / 1000 - Number(match[1])) > 300) return null;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  const received = Buffer.from(match[2], 'hex');
  if (!timingSafeEqual(expected, received)) return null;
  try {
    const event = JSON.parse(rawBody.toString('utf8'));
    return event && typeof event.id === 'string'
      && event.id === headers['wordpane-event-id'] ? event : null;
  } catch { return null; }
}

Confirme sin procesar dos veces

Responda con HTTP 2xx tras validar y registrar el evento de forma duradera. Use id para deduplicar. Hay hasta 6 intentos automáticos con esperas crecientes; se mantiene el ID y cada intento recibe una firma con timestamp nuevo. No se siguen redirecciones. El timeout de conexión es 5 segundos y el total es 10 segundos.

Edite, renueve el secreto o reintente

Editar cambia nombre, URL, eventos y límite de saldo, conservando el secreto. Cambiar la URL cancela entregas anteriores pendientes o fallidas. Eliminar un evento cancela sus entregas pendientes o fallidas. Renovar el secreto invalida el anterior inmediatamente: configure el nuevo en el receptor. No se puede editar ni renovar durante una entrega en curso.

Avisos y retención del historial

El seguimiento revisa fallos recurrentes cada 5 minutos y avisa al titular mediante la campana, sin correo ni WhatsApp. El mismo incidente no repite avisos mientras siga abierto; las nuevas incidencias respetan un mínimo de 24 horas. El seguimiento interno depende del programador y no sustituye a una supervisión externa de disponibilidad.