نظرة عامة على خطافات الويب

يسجّل Sursa حدثًا لكل تغيير مهم: نشر بطاقة أو توثيقها أو أرشفتها، وقراءة إعلان، وسؤال يبقى بلا إجابة. ويمكنك استقبال الأحداث بطريقتين، واستخدامهما معًا:

	خطافات الويب	سجل الأحداث
الطريقة	يرسل Sursa كل حدث إلى عنوان HTTPS لديك فور وقوعه.	تقرأ العملية `GET /v1/webhook-events` متى شئت.
زمن الوصول	ثوانٍ.	بقدر تكرار استطلاعك.
ما يلزم	مستقبِل HTTPS عام.	مفتاح API فقط، بالدور `admin` والنطاق `webhooks:manage`.
الاستخدام المناسب	الاستجابة للتغييرات: إرسال إشعار، أو مزامنة، أو بدء سير عمل.	مهام الدفعات، واللحاق بما فات بعد التوقف، والمطابقة.

يحمل الاثنان الأحداث نفسها بالمعرّفات نفسها. ويُحفظ كل حدث في السجل مدة 30 يومًا، سواء أكان أي خطاف ويب مشتركًا فيه أم لا.

الحدث

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

الحقل	المعنى
`id`	معرّف الحدث: `evt_` و32 حرفًا ست عشريًا. وهو نفسه في كل محاولة تسليم وفي السجل.
`type`	ما حدث، بالصيغة `<object>.<past-tense verb>`: `card.updated`، و`access_request.resolved`.
`created_at`	وقت حدوث التغيير، بتوقيت UTC.
`api_version`	إصدار واجهة API الذي يتبع `data` مخططه.
`object`	نوع الكائن الذي يتعلق به الحدث ومعرّفه.
`data`	التفاصيل. يعتمد شكلها على النوع، وهي موصوفة في كتالوج الأحداث.
`data.previous_attributes`	في أحداث `*.updated`: القيم السابقة للحقول التي تغيّرت.
`sequence`، `payload`، `test`	في تسليمات خطافات الويب فقط: الموضع في ترتيب خطاف الويب، ووضع الحمولة، وهل هذا حدث تجريبي.

لا يحتوي الحقل data إلا ما يمكن لأي قارئ للكائن أن يراه عبر واجهة API. ولا يحتوي أبدًا قوائم الوصول أو صلاحيات الآخرين أو الحقول المخفية. والأسباب في الأحداث رموز محايدة قصيرة مثل no_hits أو restricted أو index_failed.

أنواع الأحداث

تغطي الأحداث هذه المجالات:

المجال	أمثلة
البطاقات	`card.created`، `card.updated`، `card.published`، `card.archived`، `card.deleted`، `card.indexed`، `card.index_failed`
التوثيق	`card.verified`، `card.unverified`، `verification.expired`، `verification.requested`
البنية	`collection.created`، `folder.updated`
التعاون	`comment.created`، `draft.publish_requested`، `announcement.sent`، `announcement.read`
الإجابات	`question.unanswered`، `question.feedback_created`، `access_request.created`
الأشخاص والوصول	`user.created`، `user.deactivated`، `group.member_added`، `api_key.expiring`
المصادر والاستيراد	`source.sync_completed`، `import.sync_completed`، `import.document_failed`
مهام المعالجة	`job.completed`، `job.failed`، `export.ready`
خطافات الويب	`webhook.endpoint_disabled`، `webhook.ping`

القائمة الكاملة مع مخطط كل حدث ومثال عليه موجودة في كتالوج الأحداث في مرجع API. وتعيد العملية GET /v1/webhooks/catalog الأنواع المتاحة في تثبيتك.

تُضاف أنواع أحداث جديدة مع الوقت، وتكتسب الأحداث الموجودة حقولًا جديدة. ولا تُغيَّر أبدًا تسمية أنواع الأحداث ولا تُحذف. ويجب أن يتجاهل المستقبِل لديك الأنواع والحقول التي لا يعرفها.

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

لا يستقبل خطاف الويب حدثًا إلا إذا كان كائن الحدث مرئيًا له، بالطريقة نفسها التي يكون بها مرئيًا لمفتاح API: حسب دوره وملف تعريف البيانات الخاص به ومجموعاته. فخطاف الويب المقصور على المجموعة support لا يستقبل أبدًا أحداثًا عن البطاقات في finance. والأحداث عن الأشخاص والمفاتيح والمصادر وعمليات الاستيراد ومهام المعالجة وعمليات التصدير والفوترة والتطبيقات وخطافات الويب نفسها لا تذهب إلا إلى خطافات الويب ذات الدور admin.

وفي هذه الحدود، يختار كل خطاف ويب أحداثه:

حسب النوع، بالأقنعة: card.* لكل أحداث البطاقات، و* لكل الأحداث؛
حسب المجموعة والوسم، لأحداث البطاقات.

وضع الحمولة لخطاف الويب إما full (الحدث مع data، وهو الافتراضي) وإما thin (الحدث بلا data: يقرأ المستقبِل لديك الكائن عبر واجهة API بمفتاحه الخاص، فيرى دائمًا حالته الحالية).

التسليم باختصار

طلب POST عبر HTTPS يحمل الحدث بصيغة JSON، موقَّعًا بسر خطاف الويب بصيغتين: Standard Webhooks (webhook-signature) وX-KB-Signature الأقدم.
أي إجابة بالحالة 2xx خلال 10 ثوانٍ تُعدّ نجاحًا.
يُعاد إرسال التسليم الفاشل قرابة ثلاثة أيام بفواصل زمنية متزايدة. وتُحترم الترويسة Retry-After في استجابة بالحالة 429 أو 503؛ والحالة 410 تعطّل خطاف الويب؛ وبعد 10 إخفاقات متتالية يتوقف مؤقتًا حتى يُستأنف.
تُرسَل التسليمات إلى خطاف ويب واحد بالترتيب الصارم. وخطاف الويب البطيء لا يؤخر خطافات الويب الأخرى.
قد يصل الحدث نفسه أكثر من مرة: تخلّص من التكرارات حسب webhook-id.

يشرح دليل استقبال خطافات الويب مستقبِلًا كاملًا خطوة بخطوة، مع التحقق من التوقيع بلغات Node.js وPython وGo.

إدارة خطافات الويب

المهمة	نقطة النهاية
إنشاء خطاف ويب والحصول على سره	`POST /v1/webhooks`
تغيير العنوان أو الأحداث أو الحالة	`PATCH /v1/webhooks/{webhook_id}`
إرسال حدث تجريبي	`POST /v1/webhooks/{webhook_id}/test`
تدوير السر	`POST /v1/webhooks/{webhook_id}/rotate-secret`
استئناف خطاف ويب متوقف مؤقتًا	`POST /v1/webhooks/{webhook_id}/resume`
عرض التسليمات واستجابات المستقبِل	`GET /v1/webhooks/{webhook_id}/deliveries`
إعادة التسليم	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

تتطلب إدارة خطافات الويب مفتاحًا له الدور admin والنطاق webhooks:manage، أو مشرفًا في واجهة الإدارة. ويمكن أن يكون للمؤسسة حتى 20 خطاف ويب. وخطافات الويب جزء من خطة المؤسسة؛ وبدونها تجيب نقاط النهاية هذه بالحالة 403 مع الرمز webhooks.feature_disabled.