Spectra
تصفّح التوثيق

webhooks

توقيع الطلبات

كيفية توقيع طلبات POST على webhook بـ HMAC-SHA256 ليتحقّق منها سبكترا.

كل POST على webhook سبكترا يجب أن يحمل توقيع HMAC-SHA256 للجسم. الطلبات غير الموقّعة أو ذات التوقيع غير الصالح تُرفض بـ 401 Unauthorized.

التوقيع

X-Spectra-Signature: sha256=<hex>
X-Spectra-Timestamp: <unix-ms>

التوقيع يُحسب على <timestamp>.<body> (مفصول بنقطة):

import hmac, hashlib, time
secret = b"<your secret bytes>"
ts = str(int(time.time() * 1000))
body = '{"action":"buy","symbol":"BTCUSDT","qty":1}'
mac = hmac.new(secret, f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
headers = {
  "X-Spectra-Signature": f"sha256={mac}",
  "X-Spectra-Timestamp": ts,
  "Content-Type": "application/json",
}

لماذا الطابع الزمني

تضمين الطابع الزمني في الحمولة الموقّعة يربط الرسالة بلحظة. رسالة ملتقطة ومُعادة بعد نافذة ٥ دقائق تفشل التحقّق — انظر حماية الإعادة.

التحقّق من جانب الخادم

عامل سبكترا:

  1. يقرأ X-Spectra-Timestamp. يرفض إن غاب أو تجاوز ٥ دقائق.
  2. يقرأ X-Spectra-Signature. يرفض إن غاب أو فسد شكله.
  3. يعيد حساب HMAC على <timestamp>.<body> بالسرّ.
  4. يقارن بمساواة ثابتة الزمن. يرفض عند عدم التطابق.
  5. يتحقّق من مخطّط الجسم (انظر مخطّط الحمولة).
  6. يُرسل للوسيط.

أخطاء شائعة

  • توقيع الجسم دون بادئة الطابع الزمني.
  • استخدام == بدل مقارنة ثابتة الزمن على خادمك (خطر هجوم توقيت؛ ليس مشكلة سبكترا لكن يستحق ضبطه إن كنت تُوكِّل webhook الخاص بنا).
  • إرسال JSON بفروقات whitespace عما وُقِّع — وقّع دائماً البايتات الدقيقة التي ترسلها.