HTTP webhook

أرسل حمولات JSON موقّعة إلى أي نقطة نهاية HTTPS. مناسب للأنظمة الخلفية المخصصة أو n8n أو Make أو Zapier أو بنيتك التحتية الخاصة.

إعداد عنوان URL

يسلّم هدف HTTP webhook بيانات الإشارة كطلب POST بصيغة JSON إلى أي نقطة نهاية HTTPS تتحكم بها. يمكن أن تكون نقطة النهاية أي شيء يقبل HTTP: دالة serverless، أو منصة أتمتة مثل n8n أو Make، أو webhook من Zapier، أو نظامك الخلفي الخاص.

  1. 1

    انتقل إلى الأهداف، ثم هدف جديد

    في لوحة تحكم Signalync، افتح الأهداف من الشريط الجانبي وانقر على هدف جديد.
  2. 2

    اختر HTTP webhook

    اختر HTTP webhook من قائمة أنواع الأهداف.
  3. 3

    أدخل عنوان URL لنقطة النهاية

    الصق عنوان URL لنقطة نهاية HTTPS الخاصة بك. استخدم HTTPS دائمًا لتبقى بيانات الإشارة محمية أثناء النقل.
  4. 4

    أضف سر HMAC (اختياري لكنه موصى به)

    أدخل سلسلة سرية في حقل سر HMAC. سيستخدمها Signalync لتوقيع كل طلب. يمكن لنقطة النهاية لديك بعد ذلك التحقق من التوقيع للتأكد من أن الحمولة صادرة من Signalync ولم يتم العبث بها.
  5. 5

    احفظ

    انقر على حفظ. سيصبح الهدف بعد ذلك جاهزًا للإضافة إلى أي مسار.

ترويسات الطلب وإعادة المحاولات

يرسل Signalync مجموعة قياسية من الترويسات مع كل تسليم عبر HTTP webhook.

Content-Typeapplication/json
X-Signalync-Signaturesha256=<hex>. تُرسل فقط عند تعيين سر HMAC على الهدف.

يجب أن تستجيب نقطة النهاية لديك على الفور بـرمز حالة 2xx. تُعامل أي استجابة غير 2xx أو انتهاء مهلة الاتصال على أنها تسليم فاشل.

سلوك إعادة المحاولة

إذا فشل التسليم، يعيد Signalync المحاولة تلقائيًا مرة واحدة بعد بضع ثوانٍ. إذا فشلت إعادة المحاولة أيضًا، يُوسم التسليم بحالة فاشل في جدول الإشارات، ويمكنك فحص رمز حالة HTTP الذي أعادته نقطة النهاية لديك في درج تفاصيل التسليم.

التوقيع باستخدام HMAC

عند تعيين سر HMAC على الهدف، يحسب Signalync توقيع HMAC-SHA256 على جسم الطلب الخام ويرسله في الترويسة X-Signalync-Signature مسبوقًا بـ sha256=.

ينبغي أن تتحقق نقطة النهاية لديك من هذا التوقيع قبل معالجة الحمولة. إليك مثالًا بلغة Node.js:

const crypto = require("crypto");

// rawBody must be the exact bytes received, do NOT parse as JSON first
const expected = crypto
  .createHmac("sha256", SECRET)
  .update(rawBody)
  .digest("hex");

const received = req.headers["x-signalync-signature"].replace("sha256=", "");

if (
  expected.length !== received.length ||
  !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
) {
  return res.status(401).send("invalid signature");
}

// Safe to process now
const signal = JSON.parse(rawBody);
javascript
وقّع بايتات جسم الطلب الخام، وليس كائن JSON معاد تسلسله. إذا كان إطار العمل لديك يحلل الجسم تلقائيًا قبل تشغيل الـ middleware الخاص بك، فخزّن البايتات الخام مؤقتًا أولًا، على سبيل المثال مع Express: express.raw({ type: 'application/json' })

التحقق من التوقيع

إذا عيّنت سرًا على هدفك، فإن كل طلب يحمل ترويسة X-Signalync-Signature. احسب HMAC على جسم الطلب الخام وقارنه في زمن ثابت. ارفض أي شيء لا يطابق.

Node.js

const crypto = require("crypto");

function verifySignalync(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  return (
    signatureHeader.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
  );
}
javascript

Python

import hashlib
import hmac

def verify_signalync(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header, expected)
python
تُعاد محاولة التسليم مرة واحدة، بعد ثانيتين من استجابة غير 2xx. استجب بسرعة برمز 200 وأكمل المعالجة بشكل غير متزامن إذا كان المعالج لديك بطيئًا.

شكل الحمولة

يرسل Signalync كائن JSON واحدًا لكل تسليم: الحقول الأساسية بقيمها النهائية، وخريطة params تضم كل معامل آخر تم تحليله من الإشارة الأصلية، وطابع وقت التسليم.

{
  "signalId": "550e8400-e29b-41d4-a716-446655440000",
  "symbol": "XAUUSD",
  "action": "buy",
  "volume": 0.1,
  "params": {
    "vol": "0.1",
    "sl_pips": "50",
    "comment": "MyStrategy"
  },
  "timestamp": "2026-07-17T10:30:00.000Z"
}
json

راجع مرجع صيغة الإشارة للاطلاع على التعريفات الكاملة للحقول، وأنواع الحجم، وصيغة جني الأرباح المتعدد، وحقول الأوامر المعلّقة.

استكشاف الأخطاء وإصلاحها

فشل التحقق من التوقيع

السبب الأكثر شيوعًا هو توقيع كائن JSON محلل (ومعاد تسلسله) بدلًا من بايتات الجسم الخام. ستختلف المسافات وترتيب المفاتيح بعد إعادة التسلسل، مما ينتج HMAC مختلفًا. خزّن البايتات الخام مؤقتًا قبل تشغيل محلل JSON لديك. تأكد أيضًا من أن السر في نقطة النهاية لديك يطابق السر المخزن على هدف Signalync: كلاهما حساس لحالة الأحرف.

تظهر التسليمات كفاشلة بعد إعادة المحاولات

افتح الإشارة في جدول الإشارات ووسّع درج تفاصيل التسليم. يُسجل هناك رمز حالة HTTP الذي أعادته نقطة النهاية لديك. الأسباب الشائعة: إعادة نقطة النهاية رمز 4xx (تحقق من المصادقة أو تحليل الحمولة)، أو انتهاء مهلة نقطة النهاية (استجب بسرعة وانقل العمل البطيء إلى قائمة انتظار غير متزامنة)، أو تغيّر عنوان URL بعد إنشاء الهدف.

أخطاء انتهاء مهلة نقطة النهاية

يتوقع Signalync أن تؤكد نقطة النهاية لديك الاستلام بسرعة. إذا كانت معالجتك تستغرق وقتًا أطول، فاستجب فورًا برمز 200 OK وعالج الحمولة بشكل غير متزامن في الخلفية.

التسليمات المكررة

قد تتسبب إعادة المحاولات في تسليم الإشارة نفسها أكثر من مرة. استخدم الحقل signalId في الحمولة كمفتاح لعدم التكرار (idempotency): خزّنه وتجاوز المعالجة إذا سبق أن رأيته.