Webhook

Webhook mengirim peristiwa ke server Anda saat peristiwa itu terjadi, jadi Anda tidak perlu terus bertanya. Satu webhook milik satu kunci API. Webhook menerima peristiwa nomor yang dibeli dengan kunci itu, ditambah peringatan saldo rendah untuk akun Anda.

Peristiwa

Membuat webhook

Di Akun > Developer, buka kunci lalu tambahkan webhook dengan URL, peristiwa yang Anda inginkan, dan deskripsi opsional. Setiap kunci bisa punya hingga 3 webhook.

URL harus:

• diawali https://;
• memakai nama host, bukan alamat IP;
• mengarah ke alamat publik. Jaringan privat, localhost, dan rentang serupa ditolak.

Anda menerima rahasia penandatanganan yang diawali whsec_. Seperti kunci API, rahasia ini hanya ditampilkan sekali. Anda bisa menggantinya nanti, yang juga meminta kata sandi.

Bentuk pengiriman

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

Verifikasi tanda tangan

SmsGrab-Signature berisi stempel waktu t dan v1, yaitu HMAC-SHA256 dari t, sebuah titik, dan body mentah permintaan, dengan rahasia Anda sebagai kunci. Tolak pengiriman yang stempel waktunya berjarak lebih dari 300 detik dari jam Anda, dan bandingkan tanda tangan dalam waktu konstan.

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

Selalu periksa body mentah persis seperti yang Anda terima, sebelum mem-parsing JSON.

Jawab dengan cepat

Jawab dengan status 2xx apa pun dalam 10 detik dan kerjakan tugas lambat sesudahnya, misalnya di antrean. Pengalihan tidak diikuti.

Pengulangan

Pengiriman yang gagal diulang setelah 1 menit, 5 menit, 15 menit, 1 jam, 3 jam, 6 jam, 12 jam, dan 24 jam. Pengulangan membawa id peristiwa yang sama, jadi simpan id yang sudah diproses dan lewati duplikat. Peristiwa untuk satu aktivasi datang berurutan.

Penonaktifan otomatis

• Menjawab 410 Gone langsung menonaktifkan webhook.
• Setelah 50 percobaan gagal berturut-turut dalam minimal 24 jam, webhook dinonaktifkan dan Anda mendapat notifikasi. Perbaiki endpoint Anda, lalu aktifkan lagi webhook-nya.
• Mencabut kunci menonaktifkan webhook-nya.

Uji dan kirim ulang

Kirim peristiwa webhook.test dari halaman webhook untuk langsung melihat kode status, waktu respons, dan galat apa pun. Daftar pengiriman menyimpan setiap pengiriman selama 30 hari, dan Anda bisa mengirim ulang yang mana saja.