Mga webhook

Nagpapadala ang webhook ng mga event sa server mo sa sandaling mangyari ang mga ito, kaya hindi mo kailangang magtanong nang paulit-ulit. Pag-aari ng isang API key ang isang webhook. Tumatanggap ito ng mga event para sa mga numerong binili gamit ang key na iyon, at ng mga babala sa mababang balanse para sa account mo.

Mga event

Paggawa ng webhook

Sa Account > Mga developer, buksan ang isang key at magdagdag ng webhook na may URL, ang mga event na gusto mo at opsyonal na paglalarawan. Hanggang 3 webhook ang puwede sa bawat key.

Ang URL ay dapat:

• nagsisimula sa https://;
• gumagamit ng hostname, hindi IP address;
• tumuturo sa pampublikong address. Tinatanggihan ang mga pribadong network, localhost at mga katulad na range.

Makakatanggap ka ng signing secret na nagsisimula sa whsec_. Gaya ng API key, isang beses lang itong ipinapakita. Puwede mo itong palitan mamaya, at humihingi rin iyon ng password.

Anyo ng delivery

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" } } }

I-verify ang signature

Naglalaman ang SmsGrab-Signature ng timestamp na t at ng v1, ang HMAC-SHA256 ng t, isang tuldok at ng raw body ng request, na ang secret mo ang key. Tanggihan ang mga delivery na ang timestamp ay mahigit 300 segundo ang layo sa orasan mo, at ikumpara ang mga signature sa constant time.

[$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);
}

Palaging suriin ang raw body nang eksakto kung paano mo ito natanggap, bago i-parse ang JSON.

Sumagot nang mabilis

Sumagot ng anumang 2xx status sa loob ng 10 segundo at gawin ang mabagal na trabaho pagkatapos, halimbawa sa isang queue. Hindi sinusundan ang mga redirect.

Mga retry

Inuulit ang nabigong delivery pagkalipas ng 1 minuto, 5 minuto, 15 minuto, 1 oras, 3 oras, 6 na oras, 12 oras at 24 na oras. Dala ng mga retry ang parehong id ng event, kaya itabi ang mga id na naproseso na at laktawan ang mga duplicate. Dumarating nang sunud-sunod ang mga event para sa iisang activation.

Awtomatikong pag-off

• Agad na nao-off ang webhook kapag sumagot ng 410 Gone.
• Pagkatapos ng 50 sunud-sunod na nabigong pagsubok sa loob ng hindi bababa sa 24 na oras, ino-off ang webhook at makakatanggap ka ng notification. Ayusin ang endpoint mo, pagkatapos ay i-on ulit ang webhook.
• Ino-off ang mga webhook ng key kapag binawi ito.

Subukan at ipadala ulit

Magpadala ng event na webhook.test mula sa page ng webhook para agad makita ang status code, oras ng pagsagot at anumang error. Itinatabi ng listahan ng delivery ang bawat delivery sa loob ng 30 araw, at puwede mong ipadala ulit ang alinman dito.