Webhooks: receber eventos da conta

Cadastre o destino

O titular com e-mail confirmado acessa Conta → API e integrações → Webhooks → Adicionar webhook. Informe nome, URL e eventos; defina o limite para saldo baixo quando aplicável. Há até 10 destinos ativos por conta. A URL deve usar HTTPS na porta 443 com IPv4 público, sem credenciais, parâmetros de consulta ou fragmentos. Guarde o segredo mostrado uma única vez, configure-o no receptor e use Enviar teste.

Escolha os eventos

Os eventos usam POST e application/json, com identificadores e dados mínimos. Não enviam mensagens completas dos chamados nem credenciais. Respostas antigas e instalações já concluídas não são reenviadas ao cadastrar um destino.

Permissões e detalhes

server.installation.completed

server_key

ticket.reply.created

ticket_id, reply_id, from_support

balance.low

balance, threshold e currency, ao cruzar para baixo do limite; não há aviso retroativo se o saldo já estava baixo.

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 a assinatura

WordPane-Signature usa t=TIMESTAMP,v1=ASSINATURA. Calcule HMAC-SHA256 sobre timestamp + "." + corpo bruto, compare em tempo constante e rejeite diferenças superiores a 5 minutos. WordPane-Event-Id deve coincidir com id no corpo. O exemplo usa módulos nativos do 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 sem processar duas vezes

Responda com HTTP 2xx após validar e registrar o evento de forma durável. Use id para deduplicar. Há até 6 tentativas automáticas com espera crescente; o ID é mantido e cada tentativa recebe uma assinatura com timestamp novo. Redirecionamentos não são seguidos. O timeout de conexão é 5 segundos e o total é 10 segundos.

Edite, renove o segredo ou reenvie

Editar altera nome, URL, eventos e limite de saldo, mantendo o segredo. Trocar a URL cancela entregas anteriores pendentes ou com falha. Remover um evento cancela suas entregas pendentes ou com falha. Renovar segredo invalida o anterior imediatamente: configure o novo no receptor. Não é possível editar ou renovar durante uma entrega em andamento.

Avisos e retenção de históricos

O acompanhamento verifica falhas recorrentes a cada 5 minutos e avisa o titular pelo sino, sem e-mail ou WhatsApp. O mesmo incidente não repete avisos enquanto estiver aberto; novas ocorrências respeitam intervalo mínimo de 24 horas. O acompanhamento interno depende do agendador e não substitui monitoramento externo de disponibilidade.