Webhooks

تقوم Webhooks بتسليم CHAMPREPالأحداث المدعومة إلى نقطة النهاية HTTPS الخاصة بك. وهي تقلل من عمليات الاستقصاء وتسمح للتكاملات بالاستجابة للتغييرات فور حدوثها.

تتطلب إدارة Webhook ما يلي: webhooks:manage النطاق.

نقاط نهاية الإدارة

طريقة	المسار	الغرض
GET	/v1/webhooks/events	أدرج أنواع الأحداث المدعومة حاليًا.
GET	/v1/webhooks	قائمة بنقاط نهاية الويب هوك المُعدة.
POST	/v1/webhooks	قم بتسجيل نقطة نهاية HTTPS وقائمة الأحداث.
PATCH	/v1/webhooks/{webhookId}	قم بتحديث عنوان URL أو الأحداث أو الوصف أو الحالة النشطة.
DELETE	/v1/webhooks/{webhookId}	احذف نقطة النهاية.
POST	/v1/webhooks/{webhookId}/rotate-secret	قم بتدوير سر التوقيع الخاص بها.

الاستعلام /v1/webhooks/events بدلاً من الترميز الثابت لقائمة الأحداث. يمكن توسيع أنواع الأحداث المدعومة مع إضافة الخدمات لأحداث عامة.

تسجيل نقطة نهاية

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/champrep",
    "events": ["contact.created"],
    "description": "Contact synchronization"
  }' \
  https://api.champrep.com/v1/webhooks

يتم إرجاع سر التوقيع عند إنشاء نقطة النهاية أو عند تدوير سرّها. قم بتخزينه على الفور في مدير الأسرار؛ فهو ليس APIمفتاحًا حاملًا ويجب أن يكون فريدًا لنقطة نهاية الويب هوك.

تنسيق التسليم

كل عملية تسليم تتم عبر HTTPS POST مع نص JSON:

{
  "id": "delivery_identifier",
  "type": "contact.created",
  "timestamp": "2026-08-08T12:00:00Z",
  "data": {}
}

تتضمن رؤوس التسليم ما يلي:

رأس الرسالة	الغرض
X-CHAMPREP-Signature	توقيع HMAC SHA-256 في sha256=<hex> نموذج.
X-CHAMPREP-Timestamp	يُستخدم الطابع الزمني لنظام Unix في المحتوى الموقّع.
X-CHAMPREP-Delivery-Id	معرّف فريد لإزالة التكرار.
X-CHAMPREP-Event	نوع الحدث للتوجيه.

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

احسب HMAC SHA-256 على بايتات UTF-8 الدقيقة لـ <timestamp>.<raw-request-body> باستخدام سر التوقيع الخاص بنقطة النهاية. قارن التوقيعات المتوقعة والمستلمة باستخدام مقارنة ذات وقت ثابت.

import crypto from 'node:crypto';

export function verifyChamprepWebhook(rawBody, headers, secret) {
  const timestamp = String(headers['x-champrep-timestamp'] || '');
  const received = String(headers['x-champrep-signature'] || '');
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;

  const receivedBytes = Buffer.from(received);
  const expectedBytes = Buffer.from(expected);
  return receivedBytes.length === expectedBytes.length
    && crypto.timingSafeEqual(receivedBytes, expectedBytes);
}

تحقق من نص الرسالة الخام قبل أن يقوم إطار العمل بتحليله وإعادة تسلسله. قد ينتج عن الكائن المعاد تسلسله بايتات مختلفة ويفشل في التحقق.

منع إعادة التشغيل وتكرار العمل

1. ارفض أي طابع زمني يقع خارج نافذة التسامح القصيرة التي اخترتها.
2. قم بتخزين معرّفات التسليم المعالجة لمدة لا تقل عن فترة نافذة إعادة المحاولة.
3. تعامل مع معرّف التسليم المتكرر على أنه تمت معالجته بالفعل وأرسل استجابة ناجحة .
4. قم بتنفيذ الأعمال التجارية بشكل متكرر (idempotently) كلما أمكن ذلك.

سلوك التسليم

أرجع استجابة ناجحة 2xx الاستجابة الناجحة على الفور ونقل المهام المكلفة إلى قائمة انتظار. يمكن إعادة المحاولة في حالات انتهاء المهلة، وفشل الشبكة، 429، ويمكن إعادة محاولة أخطاء الخادم. قد تؤدي أخطاء مستمرة إلى تعطيل نقطة النهاية، لذا راقب حالة التسليم و قم بتصحيح عناوين URL الفاشلة على الفور.

لا تقم بتسجيل أسرار التوقيع أو الحمولات الحساسة الكاملة. قم بتدوير السر إذا كان قد تعرض للكشف، ثم قم بتحديث المستلم قبل قبول التسليمات الجديدة.