Webhooks

تتيح لك الويب هوك الصادرة تلقّي إشعارات HTTP POST فورية عند وقوع أحداث في مشروعك.

نظرة عامة

تُسلّم الويب هوك حمولة JSON إلى أي نقطة نهاية HTTPS تضبطها، كلما وقع حدث معيّن في مشروعك. ويمكن لكل ويب هوك الاشتراك في حدث واحد أو أكثر مما يلي:

الويب هوك محصورة بمشاريع بعينها. ولكل مشروع مجموعته الخاصة من نقاط النهاية بتكوينات وأسرار توقيع مستقلة.

إعداد ويب هوك

1. اذهب إلى صفحة التكاملات في مشروعك
2. مرّر إلى قسم الويب هوك الصادرة
3. انقر على إضافة ويب هوك
4. أدخل عنوان نقطة النهاية (يجب أن يكون HTTPS في بيئة الإنتاج)
5. اختر الأحداث التي تريد الاشتراك فيها
6. انقر على حفظ

بعد الحفظ، يُعرض سر توقيع مرة واحدة. انسخه فورًا — فلا يمكن استرجاعه لاحقًا. ويمكنك إعادة توليده في أي وقت من قائمة إجراءات الويب هوك.

التحقق من توقيعات الويب هوك

تتضمّن كل عملية تسليم ويب هوك ترويسة X-SupDesk-Signature تحتوي على توقيع HMAC-SHA256 لجسم الطلب. وللتحقق من ويب هوك:

1. احسب HMAC-SHA256(your_signing_secret, raw_request_body)
2. قارن النتيجة بالقيمة الست عشرية في ترويسة X-SupDesk-Signature (بعد البادئة sha256=)
3. استخدم مقارنة بزمن ثابت لمنع هجمات التوقيت

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

اختبار ويب هوك

انقر على زر اختبار بجوار ويب هوك لإرسال حمولة عيّنة إلى نقطة نهايته. تحمل حمولة الاختبار "event": "test" وحقل data.message. استخدم أداة مثل webhook.site  لفحص الطلب المُسلَّم.

سجل التسليم

يعرض سجل التسليم آخر 50 محاولة تسليم لكل ويب هوك، بما في ذلك:

• الحدث — أي حدث سُلِّم
• الحالة — success أو failed
• رمز الاستجابة — رمز حالة HTTP من نقطة النهاية
• المحاولات — عدد محاولات التسليم (بما فيها إعادات المحاولة)
• الوقت — متى جرت محاولة التسليم

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

عندما يفشل تسليم ويب هوك (استجابة 5xx أو انتهاء مهلة الشبكة)، تعيد SupDesk المحاولة حتى 3 مرات بتراجع أُسّي:

أخطاء العميل (4xx) لا يُعاد المحاولة عليها — فهي تشير إلى مشكلة دائمة في تكوين نقطة النهاية.

متطلبات الخطة

الويب هوك الصادرة متاحة في خطتَي Pro وTeam.