Webhook bildirimleri

Poll etmek hem istek harcar hem gecikme ekler. Webhook, kod düştüğü saniye sunucunuza ulaşır.

• Poll döngüsü yok: günlük istek kotanız durum sorgusu yerine gerçek işe gider.
• Daha düşük gecikme: kod bize ulaştığı anda sizin sisteminize de ulaşır, bir sonraki sorgunuzu beklemez.
• Terminal olaylar da gelir: iptal ve süre aşımı bildirimleri iade durumuyla birlikte gelir, muhasebeniz senkron kalır.

Üç olay, hepsi tek bir aktivasyon hakkında.

Her istek, zaman damgası ve ham gövdeden üretilen bir HMAC SHA256 imzası taşır.

X-SMSBulk-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
signed_string = "<t>.<raw_request_body>"

Node.js

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const pairs = header.split(',').map((p) => {
    const i = p.indexOf('=');
    return [p.slice(0, i), p.slice(i + 1)];
  });

  const t = pairs.find(([k]) => k === 't')?.[1];
  // During a rotate window more than one signature arrives: collect them all.
  const signatures = pairs.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!t || signatures.length === 0) return false;

  // Replay window: reject anything older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return signatures.some(
    (s) =>
      s.length === expected.length &&
      crypto.timingSafeEqual(
        Buffer.from(s, 'hex'),
        Buffer.from(expected, 'hex'),
      ),
  );
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    pairs = [p.split("=", 1) for p in header.split(",")]

    t = next((v for k, v in pairs if k == "t"), None)
    # During a rotate window more than one signature arrives: collect them all.
    signatures = [v for k, v in pairs if k == "v1"]
    if t is None or not signatures:
        return False

    # Replay window: reject anything older than 5 minutes.
    if abs(time.time() - int(t)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    return any(hmac.compare_digest(s, expected) for s in signatures)

Zaman damgası imzalanan dizenin parçasıdır, birkaç dakikadan eski bildirimleri reddedebilirsiniz. İmzaları sabit zamanlı karşılaştırın.

X-SMSBulk-Event-Id değerini idempotency anahtarı olarak kullanın. Aynı olayın tekrarları aynı id ile gelir.