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>.