MiniApp مقابل webhooks مساحة العمل — يغطي هذا الدليل webhooks الصادرة (كرزون تُخطر خادمك). لـ webhooks المزود الواردة المُعدّة داخل JSON لـ MiniApp، راجع Webhooks في MiniApps.
أين تدير webhooks — أنشئ واطّلع على الاشتراكات في المطوّر ← Webhooks (
/developer/webhooks) أو عبر طفرات GraphQL. ابحث في مرجع GraphQL API عن Webhook وwebhooksAdd والعمليات ذات الصلة.كيف يعمل التسليم
عند وقوع حدث، تقوم كرزون بـ:- إيجاد كل webhook نشط مشترك في زوج
type+actionذلك - بناء غلاف JSON بإصدار (انظر تنسيق الحمولة)
- توقيع الجسم الخام وإرفاق ترويسات المصادقة
- إرسال POST إلى عنوانك مع حتى 3 محاولات إعادة عند الفشل
- تسجيل كل محاولة في سجلات التسليم للتصحيح
الأمان
تأمّن كرزون حركة webhooks بـ آليتين مستقلتين في كل تسليم. استخدم واحدة أو كلتيهما للتأكد من أن الطلب جاء فعلاً من كرزون.
خلال فترة سماح تدوير السر (24 ساعة عبر
webhooksRotateSecret)، ترسل كرزون أيضاً X-Karzoun-Signature-256-Previous موقّعاً بالسر السابق حتى تتمكّن من التدوير دون توقف.
التحقق من توقيع HMAC
قيمة ترويسة التوقيع مسبوقة بـsha256=. انزع تلك البادئة، ثم قارن الباقي بـ HMAC تحسبه على بايتات الجسم الخام بالضبط (وليس كائن JSON أُعيد تسلسله).
التحقق من الرمز
قارن ترويسةKarzoun-token بـ token المُعاد عند إنشاء الـ webhook. هذا فحص سر مشترك بسيط — اقرنه بالتحقق عبر HMAC للدفاع المتعمق.
تسجيل webhook
سجّل الاشتراكات عبرwebhooksAdd. تنشئ كرزون token فريداً وsecret لـ HMAC، وتتحقق من عنوانك (HTTPS + فحوصات SSRF)، وترسل اختبار اتصال تلقائياً.
استعلم
webhooksGetActions لسرد كل حدث يمكن لمساحة عملك الاشتراك فيه. الكتالوج أدناه يعكس وحدات المنصة الحالية.token وsecret عند الإنشاء. استخدم webhooksRotateSecret لتدوير سر HMAC؛ يبقى السر السابق صالحاً لمدة 24 ساعة.
عمليات الإدارة الأخرى
تنسيق الحمولة
كل تسليم يستخدم نفس شكل الغلاف (version حالياً 1):
لأحداث
delete، يُطبَّع data إلى { "type": "<type>", "object": { "_id": "..." } }.
تستخدم اختبارات الاتصال event: "system.ping" مع رسالة اختبار قصيرة في data.
إعادة المحاولة، والمهلات، وقاطع الدائرة
كتالوج الأحداث
تُعرَّف الأحداث بـ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 حتى تعتبر كرزون التسليم ناجحاً
الخطوات التالية
- مرجع GraphQL API — ابحث عن
WebhookوWebhookDeliveryLog - المصادقة — رموز التطبيقات للوصول إلى GraphQL
- الأخطاء — تفسير استجابات أخطاء GraphQL وHTTP