GET/v1/webhook-events/{event_id}
الحصول على حدث
get_webhook_event
يعيد حدثًا من أحداث المؤسسة حسب المعرّف (evt_…)، بما في ذلك الحدث الذي لم يوضع بعد في قائمة انتظار التسليم إلى خطافات الويب. الحدث الأقدم من 30 يومًا يعيد 404. تلزم الصلاحية ORG_MANAGE_KEYS؛ ويحتاج مفتاح API إلى نطاق القراءة. أُضيف في الإصدار 1.62.0.
المصادقة
أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.
معاملات المسار
event_idstringمطلوبمعرّف الحدث (
evt_…).length ≤ 64
الاستجابات
200استجابة ناجحة
ترويسات الاستجابة
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
idstringمطلوبمعرّف الحدث (
evt_…). يُرسَل المعرّف نفسه مع تسليم خطاف الويب (X-KB-Event-Id،webhook-id).created_atstring (date-time)مطلوبوقت حدوث التغيير الذي يصفه الحدث (UTC).
org_idintegerمطلوبapi_versionstringمطلوبإصدار واجهة API العامة الذي يتبع
dataمخططه.dataobjectمطلوبحمولة الحدث. يعتمد شكلها على نوع الحدث (
GET /v1/webhooks/catalog، docs/api/webhooks.md).
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
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
404الكائن غير موجود أو غير متاح لك. لا تؤكد واجهة 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
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.code، إضافةً إلى الرموز العامة لكل طلب.
حدود المعدل
تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.