مرجع أحداث Webhooks

آخر تحديث: ٢٦ مارس ٢٠٢٦5 دقيقة قراءةمتقدمالمطور

يرسل أرقام٣٦٠ كلّ Webhook طلبَ POST بمحتوى JSON إلى نقاط النهاية التي تضيفها من الوسوم والبكسل ← Webhooks. ويحمل كلّ طلب ترويستين: X-ConsentIQ-Event وفيها اسم الحدث، و X-ConsentIQ-Signature بالصيغة t=<timestamp>,v1=<signature>. والتوقيع قيمة HMAC-SHA256 بصيغة hex، تُحسب على الطابع الزمني ثمّ نقطة ثمّ تمثيل JSON للكائن data، باستخدام سرّ التوقيع الخاصّ بنقطة النهاية. ويظهر هذا السرّ مرّة واحدة عند إنشاء نقطة النهاية، ويمكنك تدويره متى شئت.

الأحداث وحقول الحمولة

consent.created — يُرسَل كلّما سُجّل اختيار زائر: القبول أو الرفض أو حفظ التفضيلات. وإذا غيّر الزائر اختياره لاحقًا، يُنشأ سجلّ جديد وحدث جديد.
data.recordId — معرّف سجلّ الموافقة، وهو المعرّف نفسه الذي يظهر في تصدير بيانات الموافقة
data.domain — الموقع الذي تمّ فيه الاختيار
data.consent — قيمة true أو false لكلّ من necessary و analytics و marketing و functional و preferences
data.anonymousId — معرّف الزائر المجهول الذي يعيّنه الشريط
data.country — رمز بلد الزائر المكوّن من حرفين، متى أمكن تحديده
data.gpcDetected — قيمته true إذا أرسل متصفّح الزائر إشارة Global Privacy Control
data.timestamp — وقت الاختيار بصيغة ISO 8601 وبتوقيت UTC

مثال على طلب

javascript

POST https://your-server.example/webhooks/arqam360
Content-Type: application/json
X-ConsentIQ-Event: consent.created
X-ConsentIQ-Signature: t=1790000000000,v1=<hex HMAC-SHA256>

{
  "event": "consent.created",
  "timestamp": 1790000000000,
  "data": {
    "recordId": "66f0c2a1e4b0a1b2c3d4e5f6",
    "domain": "yourstore.com",
    "consent": {
      "necessary": true,
      "analytics": true,
      "marketing": false,
      "functional": false,
      "preferences": false
    },
    "anonymousId": "a1b2c3d4-...",
    "country": "SA",
    "gpcDetected": false,
    "timestamp": "2026-09-21T14:13:20.000Z"
  }
}

// التحقّق: v1 = HMAC-SHA256(secret, t + "." + JSON.stringify(body.data)) بصيغة hex

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

يُعدّ التسليم ناجحًا حين تردّ نقطة النهاية بحالة 2xx خلال 10 ثوانٍ، وما عدا ذلك يُعاد إرساله حتى 5 محاولات إجمالًا، بفواصل انتظار تقارب دقيقة ثمّ 2 ثمّ 4 ثمّ 8 دقائق. وتُحتسب كلّ محاولة فاشلة على نقطة النهاية، فإذا فشلت 10 محاولات متتالية أُوقفت نقطة النهاية تلقائيًّا. ويُصفَّر العدّاد بأوّل تسليم ناجح، أو حين تعيد تفعيل نقطة النهاية من لوحة التحكم.

اعتمد data.recordId مفتاحًا لإزالة التكرار، فقد يصلك السجلّ نفسه أكثر من مرّة: بعد إعادة محاولة لتسليم عالجه خادمك لكنّه تأخّر في الردّ، أو حين يعيد الشريط إرسال الاختيار نفسه خلال ثوانٍ. ردّ بحالة 2xx بسرعة، وأجّل المعالجة الثقيلة إلى ما بعد الردّ.

هل كانت هذه المقالة مفيدة؟

دليل إعداد Webhooks