مركز المساعدة المطورون وواجهة APIالإعداد

اشترك في Webhooks لتصلك تغييرات السجلات

بدلاً من الاستعلام المتكرر، اشترك برابط HTTPS في أحداث record.created وrecord.updated وrecord.deleted لوحدة معينة، فيرسل كورتيكسا طلباً موقّعاً عند كل تغيير.

6 دقائقحُدّث 27‏/10‏/2026

افتح في كورتيكسا

قبل أن تبدأ · شيء واحد · للمالك

مفتاح API أو رمز OAuth بنطاق read على الوحدة

مفتاح API أو رمز OAuth بنطاق read على الوحدة. راجع أنشئ مفتاح API وألغِه.

الخطوات

اعرض الأحداث المتاحة بـGET /api/v1/webhooks/events.

أنشئ الاشتراك بـPOST /api/v1/webhooks/subscriptions وجسم فيه object_slug وevents وtarget_url.

الرد يحمل signing_secret يبدأ بـwhsec_. يظهر مرة واحدة فقط، فاحفظه.

استقبل الطلبات وتحقق من التوقيع. راجع تحقق من توقيع Webhook وامنع التكرار.

رُد بـ2xx بسرعة، وأنجز المعالجة الثقيلة في الخلفية.

اعرض اشتراكاتك بـGET /webhooks/subscriptions واحذف بـDELETE /webhooks/subscriptions/:slug.

الطلب الذي يصلك

الترويسة

المعنى

X-Corteksa-Event

الحدث، مثل record.updated

X-Corteksa-Delivery

معرّف فريد للتسليم، استخدمه لمنع التكرار

X-Corteksa-Signature

t=...,v1=... للتحقق

الجسم يحمل event وevent_type وtimestamp وobject وrecord_slug وchanged_fields (قديم وجديد) وfull_record. المفاتيح معرّفات الحقول.

بلا صدى

التغيير الذي أحدثه مفتاحك لا يُرسل لاشتراك نفس المفتاح، فلا تدور المزامنة في حلقة. تغييرات المستخدمين والمفاتيح الأخرى تصلك.

الاستثناء: العمليات الجماعية فوق 100 سجل تعمل في الخلفية، فتصلك أحداث حذفها حتى لو كانت من مفتاحك. اعتبر حذف سجل محذوف لديك عملية بلا أثر.

الحذف الجماعي يُرسل حدث record.deleted لكل سجل.

الإيقاف

احذف الاشتراك، أو ألغِ المفتاح.

إذا حدثت مشكلة

ما تراه

السبب

الحل

403 Public webhooks must be managed with an API key or an OAuth token

أرسلت الطلب بجلسة مستخدم.

استخدم مفتاح API.

403 عند الإنشاء

المفتاح لا يملك read على الوحدة.

أنشئ مفتاحاً بالقراءة.

لا يصل شيء

الرابط لا يرد 2xx، أو التغيير من مفتاحك نفسه.

راجع سجلات خادمك. راجع حل أخطاء التكاملات وAPI وWebhooks.

مثال من الواقع

عيادات بسمة

الموقف

نظام الحجوزات الخارجي يحتاج معرفة كل موعد يُلغى في كورتيكسا.

ما فعلوه

اشترك المطور في record.updated على وحدة «المواعيد».
نظامه يفحص changed_fields ويلغي الحجز عند تغيّر الحالة إلى «ملغى».

النتيجة

يتحرر الموعد في نظام الحجوزات خلال ثوانٍ من إلغائه.

شركة افتراضية للتوضيح، والأرقام تقريبية.

قواعد يجب معرفتها

روابط HTTPS فقط.

الاشتراك يُدار بمفتاح API أو رمز OAuth فقط، وكل مفتاح يرى اشتراكاته فقط.

الأحداث المتاحة حالياً للسجلات فقط.

المحاولات الفاشلة تُعاد بفواصل متزايدة.

هل حلّ هذا الدليل مشكلتك؟

إن لم يحلها، سنسألك عمّا كان ناقصاً.

قد تحتاج بعد ذلك