انتقل إلى المحتوى
Sursa Developers

POST/v1/webhooks

إنشاء خطاف ويب

create_webhook

يجب أن يستخدم عنوان URL البروتوكول https، وأن يُحَلّ اسم مضيفه إلى عناوين عامة. الشبكات الخاصة (RFC 1918)، وعناوين الاسترجاع (loopback)، وعناوين link-local، وعناوين البيانات الوصفية السحابية، وغيرها من الشبكات ذات الأغراض الخاصة تُرفض عند التسجيل وعند كل اتصال. يُعرض سر التوقيع مرة واحدة في الاستجابة (secret)؛ وبعد ذلك يمكن تدويره فقط. يمكن أن يكون للمؤسسة 20 خطاف ويب على الأكثر.

يسرد الاشتراك أنواع الأحداث وأقنعة المجالات (card.*، *). يُضبط الوصول بالطريقة نفسها كما لمفتاح API: role وdata_profile_id وcollection_ids. الحدث المتعلق بكائن لا يراه الدور أو ملف تعريف البيانات أو المجموعات لا يُسلَّم. يقصر الحقل tags أحداث البطاقات على البطاقات التي تحمل أيًا من الوسوم. القيمة payload: thin ترسل الأحداث دون data. الترويسات المخصصة (headers) والتخويل الصادر (auth) تُخزَّن مشفرة؛ والاستجابات تحتوي فقط على أسماء الترويسات والعلامتين value_set وauth_set.

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات الترويسة

  • Idempotency-Keystring

    مفتاح لإعادة محاولة عملية كتابة بأمان: من 1 إلى 255 حرفًا من أحرف ASCII القابلة للطباعة؛ يُنصح بقيمة UUID v4 لكل عملية منطقية. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة لا تنفّذ العملية مرة أخرى، بل تعيد الاستجابة المحفوظة (الحالة والترويسات والنص) مع الترويسة Idempotency-Replayed: true. المفتاح نفسه مع أسلوب أو مسار أو Content-Type أو نص مختلف يعيد 409 api.idempotency_mismatch؛ وما دام الطلب الأول قيد التنفيذ، يعيد 409 api.idempotency_in_progress مع Retry-After: 1. بعد استجابة 5xx أو 429 يُحرَّر المفتاح، وتنفّذ إعادة المحاولة العملية مرة أخرى. نطاق المفتاح هو المؤسسة والجهة المستدعية (مفتاح API أو مستخدم أو مفتاح مصدر مخصص).

    length ≥ 1, length ≤ 255

نص الطلب

application/json

الكائن: WebhookCreate

  • urlstringمطلوب

    عنوان URL للمستقبِل، https:// فقط، حتى 2048 حرفًا.

    length ≤ 2048

  • descriptionstring

    length ≤ 200

  • eventsarray of WebhookEventFilterمطلوب

    items ≥ 1

  • roleWebhookRole
  • data_profile_idinteger | null
  • collection_idsarray of integer

    المجموعات التي يستقبل خطاف الويب أحداثًا عنها. غياب القيمة أو القائمة الفارغة يعني كل المجموعات المتاحة للدور وملف تعريف البيانات. والمفتاح المقصور هو نفسه على مجموعات لا ينشئ خطاف ويب إلا بقائمة غير فارغة من مجموعاته. وبدون هذا الحقل، أو مع قائمة فارغة، أو مع مجموعة خارج قائمته، يعيد الطلب 403 webhooks.collections_outside_key.

    items ≤ 200

  • tagsarray of string

    items ≤ 50

  • payloadWebhookPayloadMode
  • headersarray of WebhookHeaderInput

    items ≤ 10

  • authWebhookAuthInput

الاستجابات

201أُنشئ. هذه هي المرة الوحيدة التي يُعرض فيها `secret`.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

  • Idempotency-Replayed

    القيمة true: أُعيدت الاستجابة المحفوظة لهذا المفتاح Idempotency-Key، ولم تُنفَّذ العملية مرة أخرى.

application/json

الكائن: WebhookCreated

  • idintegerمطلوب
  • urlstringمطلوب
  • descriptionstringمطلوب
  • eventsarray of WebhookEventFilterمطلوب
  • activebooleanمطلوب
  • statusWebhookStatusمطلوب
  • paused_atstring (date-time) | null
  • paused_reasonstring | null

    القيمة failures: 10 محاولات فاشلة متتالية؛ والقيمة feature_disabled: الخطة لا تشمل خطافات الويب.

  • disabled_reasonstring | null

    القيمة gone: أجاب المستقبِل بالرمز 410؛ والقيمة manual: عطّله مشرف.

    القيم المسموح بها: gonemanualnull

  • disabled_atstring (date-time) | null
  • roleWebhookRoleمطلوب
  • data_profile_idinteger | null

    ملف تعريف البيانات لخطاف الويب (القيمة null تعني بلا ملف تعريف، كما في مفتاح API بالدور نفسه).

  • collection_idsarray of integerمطلوب

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

  • tagsarray of stringمطلوب

    أحداث البطاقات فقط للبطاقات التي تحمل أيًا من هذه الوسوم؛ والقائمة الفارغة تعني بلا تصفية.

  • payloadWebhookPayloadModeمطلوب
  • headersarray of WebhookHeaderمطلوب
  • auth_typestring | null

    نوع التخويل الصادر (القيمة null تعني بلا تخويل).

    القيم المسموح بها: bearerbasicnull

  • auth_setbooleanمطلوب

    يشير إلى ضبط التخويل الصادر (لا تُعاد القيم أبدًا).

  • previous_secret_valid_untilstring (date-time) | null

    الوقت الذي تُوقَّع التسليمات حتى حلوله بالسر السابق أيضًا (القيمة null تعني أنه لا توجد فترة تداخل).

  • healthWebhookHealth
  • consecutive_failuresintegerمطلوب
  • last_delivery_atstring (date-time) | null
  • last_success_atstring (date-time) | null
  • last_errorstring | null
  • created_byinteger | null
  • created_by_namestring | null
  • created_atstring (date-time)مطلوب
  • updated_atstring (date-time)مطلوب
  • secretstringمطلوب

    القيمة whsec_ يليها 32 بايتًا بترميز base64 (الأسرار الجديدة تستخدم الأبجدية القياسية مع الحشو، والأقدم تستخدم base64url). احفظه لدى المستقبِل؛ فلن يظهر في استجابات API مرة أخرى. مفتاح التوقيع وفق Standard Webhooks هو ناتج فك ترميز base64 للجزء الذي بعد whsec_.

  • previous_valid_untilstring (date-time) | null

    الوقت الذي يظل السر السابق مقبولًا حتى حلوله (بعد التدوير). القيمة null عند الإنشاء.

400الطلب غير صالح: قيمة معامل أو حالة الكائن لا تسمح بالإجراء (الحقل `detail` رسالة نصية).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

401لم تُرسَل بيانات اعتماد (لا ملف تعريف ارتباط للجلسة ولا مفتاح API)، أو لم يُعثر على المفتاح.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

403الإجراء غير مسموح: الدور غير كافٍ، أو لا وصول إلى المجموعة أو البطاقة، أو يعمل الطلب في وضع «View as»، أو المؤسسة معلّقة أو محذوفة (الحقل `detail` كائن فيه `code: org_suspended | org_deleted`).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

409حالة الكائن لا تسمح بالإجراء، مثل التكرار، أو فهرسة جارية، أو مهمة معالجة عولجت بالفعل.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

422خطأ في صحة البيانات: نص الطلب أو المعاملات لا تطابق المخطط (الحقل `detail` قائمة بأخطاء صحة البيانات)، أو قيمة معامل خارج النطاق المسموح (الحقل `detail` رسالة نصية).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

429طلبات كثيرة جدًا (`api.rate_limited`)، أو استُنفدت حصة المؤسسة للدقيقة أو اليوم أو الشهر (`api.quota_exceeded`؛ يحتوي الحقل `error.details` على `quota` و`limit` و`reset_at`)، أو بلغت المؤسسة حدها، أو خدمة الإجابات مشغولة (`answers.engine_busy`). انتظر المدة المذكورة في الترويسة `Retry-After`.

ترويسات الاستجابة

  • Retry-After

    عدد الثواني التي تنتظرها قبل إعادة محاولة الطلب.

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

رموز الأخطاء

الرموز التي قد تعيدها نقطة النهاية هذه في error.code، إضافةً إلى الرموز العامة لكل طلب.

إعادة المحاولة بأمان

أرسل الترويسة Idempotency-Key (قيمة UUID مثلًا) مع كل طلب POST وPATCH. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← webhooks · مرجع API