Skip to main content
تُسلّم webhooks كرزون إشعارات HTTP فورية عند حدوث تغيير في مساحة عملك. سجّل نقطة نهاية HTTPS، واختر الأحداث التي تهمك، وترسل كرزون POST بحمولة JSON منظّمة كلما أُطلقت — مثلاً عند تعيين محادثة، أو تحديث عميل، أو اكتمال تدفق واتساب. استخدم webhooks لمزامنة بيانات CRM، أو تشغيل أتمتة في بنيتك، أو إخطار أنظمة خارجية، أو تغذية تدفقات الأحداث إلى مسار التحليلات لديك.
MiniApp مقابل webhooks مساحة العمل — يغطي هذا الدليل webhooks الصادرة (كرزون تُخطر خادمك). لـ webhooks المزود الواردة المُعدّة داخل JSON لـ MiniApp، راجع Webhooks في MiniApps.
أين تدير webhooks — أنشئ واطّلع على الاشتراكات في المطوّر ← Webhooks (/developer/webhooks) أو عبر طفرات GraphQL. ابحث في مرجع GraphQL API عن Webhook وwebhooksAdd والعمليات ذات الصلة.

كيف يعمل التسليم

عند وقوع حدث، تقوم كرزون بـ:
  1. إيجاد كل webhook نشط مشترك في زوج type + action ذلك
  2. بناء غلاف JSON بإصدار (انظر تنسيق الحمولة)
  3. توقيع الجسم الخام وإرفاق ترويسات المصادقة
  4. إرسال POST إلى عنوانك مع حتى 3 محاولات إعادة عند الفشل
  5. تسجيل كل محاولة في سجلات التسليم للتصحيح
يجب أن تعيد نقطة نهايتك أي حالة 2xx ضمن مهلة الاتصال. الاستجابات غير 2xx وأخطاء الشبكة تشغّل إعادة المحاولة التلقائية مع تأخير أسي.

الأمان

تأمّن كرزون حركة webhooks بـ آليتين مستقلتين في كل تسليم. استخدم واحدة أو كلتيهما للتأكد من أن الطلب جاء فعلاً من كرزون. خلال فترة سماح تدوير السر (24 ساعة عبر webhooksRotateSecret)، ترسل كرزون أيضاً X-Karzoun-Signature-256-Previous موقّعاً بالسر السابق حتى تتمكّن من التدوير دون توقف.
تحقق دائماً من الرمز أو التوقيع قبل معالجة الحمولة. إذا لم يطابق أي منهما، أجب بـ 401 وتجاهل الجسم.

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

قيمة ترويسة التوقيع مسبوقة بـ sha256=. انزع تلك البادئة، ثم قارن الباقي بـ HMAC تحسبه على بايتات الجسم الخام بالضبط (وليس كائن JSON أُعيد تسلسله).

التحقق من الرمز

قارن ترويسة Karzoun-token بـ token المُعاد عند إنشاء الـ webhook. هذا فحص سر مشترك بسيط — اقرنه بالتحقق عبر HMAC للدفاع المتعمق.

تسجيل webhook

سجّل الاشتراكات عبر webhooksAdd. تنشئ كرزون token فريداً وsecret لـ HMAC، وتتحقق من عنوانك (HTTPS + فحوصات SSRF)، وترسل اختبار اتصال تلقائياً.
استعلم webhooksGetActions لسرد كل حدث يمكن لمساحة عملك الاشتراك فيه. الكتالوج أدناه يعكس وحدات المنصة الحالية.
جرّب هذا في ساحة GraphQL.
احفظ بيانات الاعتماد فوراً. يُعاد token وsecret عند الإنشاء. استخدم webhooksRotateSecret لتدوير سر HMAC؛ يبقى السر السابق صالحاً لمدة 24 ساعة.

عمليات الإدارة الأخرى

تنسيق الحمولة

كل تسليم يستخدم نفس شكل الغلاف (version حالياً 1):
لأحداث delete، يُطبَّع data إلى { "type": "<type>", "object": { "_id": "..." } }. تستخدم اختبارات الاتصال event: "system.ping" مع رسالة اختبار قصيرة في data.

إعادة المحاولة، والمهلات، وقاطع الدائرة

أعد 2xx فور قبول الحمولة. انقل العمل الثقيل إلى طابور خلفية — المعالجات البطيئة تعرضك للمهلات وإعادة المحاولة.
قد يصل نفس الحدث المنطقي أكثر من مرة (id يبقى ثابتاً عبر المحاولات؛ metadata.deliveryId يتغير لكل محاولة). صمّم المعالجات لتتحمّل التكرار.

كتالوج الأحداث

تُعرَّف الأحداث بـ type (الوحدة + المورد) و**action** (ما حدث). في الحمولة المُسلَّمة تظهر كـ event: "<type>.<action>". استعلم webhooksGetActions للقائمة الحية. الاشتراكات أدناه مجمّعة حسب وحدة المنصة.

العملاء (core:customer)

المحادثات والبريد الوارد (inbox:*)

واتساب (whatsapp:*)

المهام (tasks:*)

الاجتماعات (meetings:meeting)

ساعة الدوام (timeclock:*)

النظام

استكشاف الأخطاء

تأكد أن كرزون ترسل الأحداث

  • افتح المطوّر ← Webhooks ← سجلات التسليم للاشتراك
  • نفّذ webhooksPing وتحقق من تسليم system.ping بحالة success
  • وجّه العنوان مؤقتاً إلى webhook.site لفحص الطلبات الخام

افحص نقطة نهايتك

متطلبات التحقق من العنوان

  • يجب أن يكون HTTPS
  • يجب أن يُحل إلى عنوان IP عام (النطاقات الخاصة وlocalhost محظورة لحماية SSRF)
  • يجب أن يعيد 2xx حتى تعتبر كرزون التسليم ناجحاً

الخطوات التالية

اسرد webhooks في الساحة: query { webhooks(page: 1, perPage: 5) { data { _id name url status isActive } } }
آخر تعديل في ٨ أغسطس ٢٠٢٦