Webhooks

Os webhooks enviam eventos para o seu servidor no momento em que acontecem, então você não precisa ficar consultando. Um webhook pertence a uma chave de API. Ele recebe os eventos dos números comprados com essa chave, além dos alertas de saldo baixo da sua conta.

Eventos

Criar um webhook

Em Conta > Desenvolvedores, abra uma chave e adicione um webhook com a URL, os eventos desejados e uma descrição opcional. Cada chave pode ter até 3 webhooks.

A URL precisa:

• começar com https://;
• usar um nome de host, não um endereço IP;
• levar a um endereço público. Redes privadas, localhost e faixas parecidas são recusadas.

Você recebe um segredo de assinatura que começa com whsec_. Assim como uma chave de API, ele é mostrado só uma vez. Você pode trocá-lo depois, o que também pede sua senha.

Como é uma entrega

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: SmsGrab-Webhooks/1.0
SmsGrab-Event: activation.code_received
SmsGrab-Delivery: 9f7d6c1e-2b44-4c1a-8f0e-6a3d2c1b0e9f
SmsGrab-Signature: t=1790503200,v1=3b9a0c…

{ "id": "evt_4e1f…", "type": "activation.code_received", "created_at": "2026-09-27T10:06:12.004Z",
  "api_version": "2026-09-27", "data": { "activation": { "id": "5c1d0c2e-…", "status": "CODE_RECEIVED" } } }

Verifique a assinatura

SmsGrab-Signature contém um carimbo de tempo t e v1, o HMAC-SHA256 de t, um ponto e o corpo bruto da requisição, usando seu segredo como chave. Rejeite entregas cujo carimbo de tempo esteja a mais de 300 segundos do seu relógio e compare as assinaturas em tempo constante.

[$t, $v1] = (function (string $h): array {
    parse_str(str_replace(',', '&', $h), $p);
    return [(int) ($p['t'] ?? 0), (string) ($p['v1'] ?? '')];
})($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $t.'.'.$body, getenv('SMSGRAB_WEBHOOK_SECRET'));
$ok = abs(time() - $t) <= 300 && hash_equals($expected, $v1);

import hmac, hashlib, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - t) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))

import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t ?? 0);
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return Math.abs(Date.now() / 1000 - t) <= 300 && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}

Sempre verifique o corpo bruto exatamente como você o recebeu, antes de interpretar o JSON.

Responda rápido

Responda com qualquer status 2xx em até 10 segundos e faça o trabalho demorado depois, por exemplo em uma fila. Redirecionamentos não são seguidos.

Novas tentativas

Uma entrega que falhou é tentada de novo depois de 1 minuto, 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas, 12 horas e 24 horas. Uma nova tentativa repete o mesmo id do evento, então guarde os ids já processados e ignore duplicados. Os eventos de uma ativação chegam em ordem.

Desativação automática

• Responder 410 Gone desativa o webhook na hora.
• Depois de 50 tentativas seguidas que falharam ao longo de pelo menos 24 horas, o webhook é desativado e você recebe uma notificação. Corrija seu endpoint e depois ative o webhook de novo.
• Revogar uma chave desativa os webhooks dela.

Testar e reenviar

Envie um evento webhook.test pela página do webhook para ver na hora o código de status, o tempo de resposta e qualquer erro. A lista de entregas guarda cada entrega por 30 dias, e você pode reenviar qualquer uma delas.