إنتقل إلى المحتوى الرئيسي

Webhooks

الـ Webhooks هي إشعارات HTTP لحظية تُرسَل إلى خادمك لما تحدث أحداث في Orki. بدل الاستطلاع لمعرفة التغييرات، يستلم نظامك تحديثات فورية لما تصل رسالة، تتغير حالة محادثة، أو تحدث أحداث أخرى.

المسار: الإعدادات > رموز الوصول (بطاقة الـ Webhook)

تسجيل webhook​

  1. اذهب إلى الإعدادات > رموز الوصول وابحث عن بطاقة الـ Webhook
  2. اضغط على "إضافة Webhook"
  3. أدخل رابط webhook (يجب أن يكون HTTPS)
  4. أدخل رمز التحقق (سلسلة تُستخدم فقط في مصافحة التحقق عبر GET)
  5. اختر أنواع الأحداث التي تريد الاشتراك فيها

بعد التسجيل، يعرض لك Orki سر الـ webhook مرة واحدة — احفظه بأمان. هذا السر (وليس رمز التحقق) هو مفتاح HMAC الذي يُوقَّع به كل تسليم.

أنواع الأحداث​

الحدثالوصف
meta.messageاستُلِمَت رسالة من واتساب/إنستغرام
message.createdأُنشِئَت رسالة جديدة (واردة أو صادرة)
chat.status_changedتغيّرت حالة محادثة (نشطة، مؤجَّلة، مغلقة، يحتاج اهتماماً)

مصافحة التحقق​

لما تسجّل webhook، يرسل Orki طلب GET إلى رابطك للتحقق من الملكية:

  1. يرسل Orki طلب GET مع معامل hub.challenge ورمز التحقق عندك
  2. يتحقق خادمك أن رمز التحقق يطابق ما ضبطته
  3. يردّ خادمك بقيمة hub.challenge في متن الاستجابة

هذا يؤكد أنك تملك نقطة النهاية وأنك جاهز لاستقبال الأحداث.

التحقق من توقيع HMAC-SHA256​

تتضمن كل حمولة webhook ترويسة X-Orki-Signature-256 تحتوي على sha256=<hex_digest> لمتن الطلب. مفتاح HMAC هو سر الـ webhook الذي يُعرَض مرة واحدة عند التسجيل — وليس رمز التحقق (رمز التحقق يُستخدم فقط في مصافحة التحقق عبر GET).

تحقق دائماً من التوقيعات لضمان أن الحمولات حقيقية من Orki.

مثال (Node.js)​

const crypto = require('crypto');

// webhookSecret = the secret shown once when you registered the webhook
function verifySignature(payload, signature, webhookSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// signature = req.headers['x-orki-signature-256']
ملاحظة

استخدم timingSafeEqual (أو ما يعادله في لغتك) لمنع هجمات التوقيت عند مقارنة التوقيعات.

سجلات التسليم​

اعرض سجل التسليم لكل webhook لمراقبة وتصحيح تكاملك.

ما تقدر تشاهد​

  • نوع الحدث — أي حدث شغّل التسليم
  • رمز حالة الاستجابة — ما الذي ردّ به خادمك
  • وقت الاستجابة — كم استغرق خادمك للرد
  • الوقت — متى تمت محاولة التسليم
  • تفاصيل الخطأ — تُعرَض للتسليمات الفاشلة

التصفية​

صفِّ سجلات التسليم حسب:

  • نوع الحدث
  • النجاح أو الفشل
  • النطاق الزمني

سلوك إعادة المحاولة​

تُعاد محاولة التسليمات الفاشلة تلقائياً حتى 3 مرات، بتباعد تقريبي ثانية واحدة، ثم 5 ثوانٍ، ثم 30 ثانية. يتتبع Orki عدد الإخفاقات لكل webhook — الـ webhooks ذات إخفاقات متتالية كثيرة جداً تعرض تحذيراً في لوحة التحكم.

أحداث الاختبار​

قبل التشغيل، استخدم ميزة حدث الاختبار للتحقق من أن نقطة النهاية عندك تعمل بشكل صحيح. هذا يرسل حمولة نموذجية إلى رابط webhook عندك عشان تقدر تتأكد أن كل شيء مربوط بشكل صحيح.

warning

تأكد أن نقطة النهاية عندك تردّ بـ رمز حالة 2xx خلال 10 ثوانٍ، وإلا سوف يُوسَم التسليم كفاشل.

تلميح

استخدم سجلات التسليم لتصحيح مشاكل التكامل — تعرض بالضبط ما أُرسِل وما ردّ به خادمك.

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

  • رموز الوصول — أنشئ وصولاً برمجياً لـ API للأنظمة الخارجية
  • أحداث النظام — المرآة الواردة للـ Webhooks: نظامك الخلفي يطلق أحداثاً منظَّمة على محادثة