Pular para conteúdo

Webhooks

A plataforma avisa seu sistema por HTTP POST, em JSON, a cada evento. A URL de destino e o segredo de assinatura são configurados no portal ou pelo seu provedor.

Eventos

Evento Quando
message.status A operadora aceitou ou recusou (sent, rejected) e quando chega o recibo (delivered, failed)
message.received Um aparelho respondeu a um remetente numérico seu
balance.low O saldo pré-pago chegou ao limite de alerta
batch.completed Um lote terminou ou foi cancelado
rcs.status Mudança de status de uma mensagem RCS
rcs.received Resposta ou toque em botão de uma mensagem RCS

Os campos de cada evento estão na referência da API, seção Webhooks.

Cabeçalhos

Cabeçalho Conteúdo
X-Webhook-Id Identificador único da entrega; use para descartar duplicados
X-Webhook-Event Nome do evento
X-Webhook-Signature t=<segundos unix>,v1=<hex>

Verificar a assinatura

v1 é HMAC-SHA256(segredo, "<t>.<corpo bruto>") em hexadecimal. Calcule sobre o corpo exatamente como chegou, antes de qualquer parse de JSON, e recuse timestamps com mais de 5 minutos.

const crypto = require('crypto');
function verificar(corpoBruto, cabecalho, segredo) {
  const { t, v1 } = Object.fromEntries(cabecalho.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const esperado = crypto.createHmac('sha256', segredo).update(`${t}.${corpoBruto}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}
import hmac, hashlib, time
def verificar(corpo_bruto: bytes, cabecalho: str, segredo: str) -> bool:
    partes = dict(p.split('=', 1) for p in cabecalho.split(','))
    if abs(time.time() - int(partes['t'])) > 300:
        return False
    esperado = hmac.new(segredo.encode(), partes['t'].encode() + b'.' + corpo_bruto,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(partes['v1'], esperado)
function verificar(string $corpoBruto, string $cabecalho, string $segredo): bool {
    parse_str(str_replace(',', '&', $cabecalho), $p);
    if (abs(time() - (int)$p['t']) > 300) return false;
    $esperado = hash_hmac('sha256', $p['t'] . '.' . $corpoBruto, $segredo);
    return hash_equals($esperado, $p['v1']);
}
// $corpoBruto = file_get_contents('php://input');

Respostas e novas tentativas

Responda com qualquer status 2xx em até 10 segundos. Caso contrário, a entrega é repetida depois de 10 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h e 6 h; depois disso é descartada.

Processe em segundo plano

Grave o evento e responda 200 na hora. Processamento demorado dentro da requisição gera novas tentativas e eventos duplicados.

A entrega é pelo menos uma vez e pode chegar fora de ordem. Use X-Webhook-Id para descartar duplicados e o campo occurred_at para ficar sempre com o estado mais recente.

Se o seu sistema ficou fora do ar, recupere as respostas perdidas com GET /sms/received?after_id=<último seq processado>.