Webhooklar

Webhooklar olayları gerçekleştikleri anda sunucuna gönderir; böylece sürekli sorgulaman gerekmez. Bir webhook bir API anahtarına aittir. O anahtarla alınan numaraların olaylarını ve hesabın için düşük bakiye uyarılarını alır.

Olaylar

Webhook oluştur

Hesap > Geliştiriciler sayfasında bir anahtar aç ve adresi, istediğin olayları ve isteğe bağlı bir açıklamayı girerek webhook ekle. Her anahtarın en fazla 3 webhooku olabilir.

Adres şu koşulları sağlamalı:

• https:// ile başlamalı;
• IP adresi değil, bir alan adı kullanmalı;
• herkese açık bir adrese gitmeli. Özel ağlar, localhost ve benzeri aralıklar reddedilir.

whsec_ ile başlayan bir imza anahtarı alırsın. API anahtarı gibi yalnızca bir kez gösterilir. Daha sonra değiştirebilirsin; bu da şifreni ister.

Bir gönderim nasıl görünür?

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

İmzayı doğrula

SmsGrab-Signature, bir zaman damgası t ile v1 değerini içerir. v1, t, bir nokta ve ham istek gövdesinin senin gizli anahtarınla hesaplanan HMAC-SHA256 değeridir. Zaman damgası saatinden 300 saniyeden fazla farklı olan gönderimleri reddet ve imzaları sabit sürede karşılaştır.

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

JSON'u ayrıştırmadan önce her zaman gövdeyi tam olarak aldığın haliyle doğrula.

Hızlı yanıt ver

10 saniye içinde herhangi bir 2xx durumuyla yanıt ver, yavaş işleri sonra, örneğin bir kuyrukta yap. Yönlendirmeler izlenmez.

Yeniden denemeler

Başarısız bir gönderim 1 dakika, 5 dakika, 15 dakika, 1 saat, 3 saat, 6 saat, 12 saat ve 24 saat sonra yeniden denenir. Yeniden deneme aynı olay id değerini taşır; işlediğin kimlikleri sakla ve tekrarları atla. Bir aktivasyonun olayları sırayla gelir.

Otomatik kapanma

• 410 Gone yanıtı webhooku hemen kapatır.
• En az 24 saate yayılan art arda 50 başarısız denemeden sonra webhook kapatılır ve bir bildirim alırsın. Uç noktanı düzelt, sonra webhooku yeniden aç.
• Bir anahtarı iptal etmek webhooklarını kapatır.

Test et ve yeniden gönder

Durum kodunu, yanıt süresini ve varsa hatayı hemen görmek için webhookun sayfasından bir webhook.test olayı gönder. Gönderim listesi her gönderimi 30 gün saklar ve istediğini yeniden gönderebilirsin.