Webhook

Webhook menghantar peristiwa ke pelayan anda sebaik sahaja ia berlaku, jadi anda tidak perlu bertanya berulang kali. Satu webhook milik satu kunci API. Ia menerima peristiwa bagi nombor yang dibeli dengan kunci itu, serta amaran baki rendah untuk akaun anda.

Peristiwa

Mencipta webhook

Dalam Akaun > Pembangun, buka kunci dan tambah webhook dengan URL, peristiwa yang anda mahu dan penerangan pilihan. Setiap kunci boleh mempunyai sehingga 3 webhook.

URL mesti:

• bermula dengan https://;
• menggunakan nama hos, bukan alamat IP;
• menghala ke alamat awam. Rangkaian persendirian, localhost dan julat seumpamanya ditolak.

Anda menerima rahsia tandatangan yang bermula dengan whsec_. Seperti kunci API, ia hanya dipaparkan sekali. Anda boleh menukarnya kemudian, dan itu juga meminta kata laluan.

Bentuk penghantaran

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

Sahkan tandatangan

SmsGrab-Signature mengandungi cap masa t dan v1, iaitu HMAC-SHA256 bagi t, satu titik dan badan mentah permintaan, dengan rahsia anda sebagai kunci. Tolak penghantaran yang cap masanya berbeza lebih daripada 300 saat daripada jam anda, dan bandingkan tandatangan dalam masa malar.

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

Sentiasa semak badan mentah tepat seperti yang diterima, sebelum menghurai JSON.

Jawab dengan pantas

Jawab dengan mana-mana status 2xx dalam 10 saat dan lakukan kerja yang perlahan kemudian, contohnya dalam baris gilir. Ubah hala tidak diikuti.

Cubaan semula

Penghantaran yang gagal dicuba semula selepas 1 minit, 5 minit, 15 minit, 1 jam, 3 jam, 6 jam, 12 jam dan 24 jam. Cubaan semula membawa id peristiwa yang sama, jadi simpan id yang telah diproses dan langkau pendua. Peristiwa bagi satu pengaktifan tiba mengikut urutan.

Penyahaktifan automatik

• Menjawab 410 Gone terus menyahaktifkan webhook.
• Selepas 50 cubaan gagal berturut-turut dalam sekurang-kurangnya 24 jam, webhook dinyahaktifkan dan anda menerima pemberitahuan. Baiki endpoint anda, kemudian aktifkan semula webhook.
• Membatalkan kunci menyahaktifkan webhooknya.

Uji dan hantar semula

Hantar peristiwa webhook.test dari halaman webhook untuk terus melihat kod status, masa respons dan sebarang ralat. Senarai penghantaran menyimpan setiap penghantaran selama 30 hari, dan anda boleh menghantar semula mana-mana satu.