إشعارات ويب هوك

الاستعلام المتكرر يستهلك الطلبات ويضيف تأخيرًا. الويب هوك يصل إلى خادمك في نفس الثانية التي يصل فيها الرمز.

• لا حلقة استعلام: حصتك اليومية من الطلبات تذهب إلى العمل الحقيقي بدل فحص الحالة.
• زمن استجابة أقل: الرمز يصل إلى نظامك فور وصوله إلينا، لا عند استعلامك التالي.
• الأحداث النهائية أيضًا: الإلغاء وانتهاء المهلة يصلان مع حالة الاسترداد، فتبقى حساباتك متوافقة.

ثلاثة أحداث، جميعها عن تفعيل واحد.

كل طلب يحمل توقيع HMAC SHA256 مبنيًا على الطابع الزمني والجسم الخام.

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)

الطابع الزمني جزء من النص الموقّع، لذا يمكنك رفض ما مضى عليه أكثر من بضع دقائق. قارن التواقيع بزمن ثابت.

استخدم X-SMSBulk-Event-Id مفتاحًا للتكرار الآمن. محاولات نفس الحدث تحمل المعرّف ذاته.