إدارة Webhooks: الإنشاء والاختبار والمصادقة

تتيح Webhooks لـ AgencyHandy دفع البيانات إلى أنظمتك الخارجية في اللحظة التي يتغير فيها شيء ما — دون الحاجة إلى الاستطلاع الدوري. عند إطلاق حدث مُكوَّن (على سبيل المثال، تحديث طلب أو إنشاء تذكرة)، ترسل AgencyHandy طلب HTTP POST مع حمولة JSON إلى عنوان URL الذي تحدده. يجعل هذا من السهل إبقاء الأدوات الخارجية مثل أنظمة إدارة علاقات العملاء (CRMs) وأنظمة الفوترة ولوحات المعلومات المخصصة متزامنة مع مساحة عمل AgencyHandy في الوقت الفعلي.

تدعم مساحات عمل خطة Business Pro ما يصل إلى 30,000 حدث webhook لكل فترة فوترة. تحقق من حدود خطتك قبل إعداد أتمتة ذات حجم كبير.

الأحداث المدعومة

يمكنك الاشتراك في webhook لأي مجموعة من الأحداث التالية:

الفئة	الأحداث
الخدمة	الإنشاء، التحديث، الحذف
الطلب	الإنشاء، التحديث، الحذف
المهمة	الإنشاء، التعيين، الإكمال، التحديث
الفاتورة	تغيير الحالة
العميل / المستخدم	إضافة عميل جديد، حذف عميل/مستخدم
العرض	الإرسال، الاستلام، القبول، الرفض
التذكرة	الإنشاء، التعيين، تغيير الحالة
الدفع	الاستلام، الفشل
حزمة الخدمة	الإنشاء، التحديث، الحذف

إنشاء webhook

الانتقال إلى إدارة Webhooks

في الشريط الجانبي الأيسر، انتقل إلى التكاملات ← إدارة Webhooks.

مصادقة الرمز الخاص بك

انقر على زر الإدارة لمصادقة رمز webhook الخاص بك. يُستخدم هذا الرمز لتوقيع الحمولات الصادرة حتى تتمكن من التحقق من أنها صادرة من AgencyHandy.

إنشاء webhook جديد

انقر على إنشاء Webhook جديد لفتح نموذج تكوين webhook.

إدخال عنوان URL للنقطة النهائية

في حقل عنوان URL للنقطة النهائية، أدخل عنوان URL للنظام الخارجي الذي يجب أن يستقبل بيانات webhook. يجب أن يكون هذا نقطة نهائية POST يمكن الوصول إليها علنًا.

اختيار نوع المحتوى

اختر JSON كنوع المحتوى. ترسل AgencyHandy جميع حمولات webhook بصيغة application/json.

اختيار أحداث webhook

اختر كل حدث يجب أن يُشغّل هذا webhook. يمكنك اختيار أحداث من فئات متعددة — على سبيل المثال، الطلب: تم الإنشاء والفاتورة: تغيير الحالة يمكن أن يشيرا إلى نفس النقطة النهائية.

تفعيل webhook

فعّل زر نشط. عند التفعيل، تُرسل AgencyHandy الحمولات لجميع الأحداث المختارة إلى نقطتك النهائية في الوقت الفعلي.

حفظ التكوين

راجع إعداداتك، ثم انقر على حفظ. يظهر webhook في القائمة ويبدأ في تسليم الأحداث فورًا.

اختبار webhook

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

فتح webhook

من قائمة إدارة Webhooks، انقر على webhook الذي تريد اختباره.

النقر على اختبار الحدث

انقر على زر اختبار الحدث في صفحة تفاصيل webhook.

اختيار حدث اختبار

اختر حدثًا نموذجيًا من قائمة الأحداث المُكوَّنة على هذا webhook (مثل الطلب: تم الإنشاء).

إرسال حمولة الاختبار

انقر على إرسال. تنشر AgencyHandy حمولة نموذجية إلى عنوان URL لنقطتك النهائية.

التحقق من النتيجة

تحقق من نظامك الخارجي للتأكد من وصول حمولة الاختبار ومعالجتها كما هو متوقع. في AgencyHandy، انقر داخل webhook لمراجعة السجل الخاص به — يمكنك رؤية الطلب الكامل والاستجابة التي أعادتها نقطتك النهائية، وإعادة تسليم أي حدث سابق إذا لزم الأمر.

استخدم أداة مثل Webhook.site أو RequestBin كنقطة نهائية مؤقتة أثناء الإعداد لفحص شكل الحمولة الدقيق قبل ربط نظامك الفعلي.

مصادقة حمولات webhook

كل طلب webhook صادر من AgencyHandy يتضمن ترويسة توقيع يمكن لنقطتك النهائية استخدامها للتحقق من أن الحمولة أصيلة ولم يتم العبث بها.

ترويسة التوقيع

x-ah-sig: <signature>

تضيف AgencyHandy هذه الترويسة إلى كل طلب webhook. استخرج القيمة من الطلبات الواردة ومررها إلى نقطة نهاية التحقق.

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

أرسل الطلب التالي للتأكد من صحة الحمولة:

POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json

string

مطلوب

معرّف webhook الذي استقبل الحدث. ابحث عنه في صفحة تفاصيل webhook في AgencyHandy.

string

مطلوب

قيمة ترويسة x-ah-sig من طلب webhook الوارد.

string

مطلوب

السر الخاص بـ webhook المعروض في صفحة تفاصيله في AgencyHandy.

object

مطلوب

نص JSON الخام المستلم من طلب webhook الخاص بـ AgencyHandy.

const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }

curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
  -H "Content-Type: application/json" \
  -d '{
    "webhookId": "your_webhook_id",
    "signature": "your_signature",
    "secret": "your_webhook_secret",
    "payload": {}
  }'

الاستجابات

string

SUCCESS عند صحة التوقيع. FAILED عند فشل التحقق (HTTP 403).

Success (200)

{
  "verification_status": "SUCCESS"
}

Failure (403)

{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}

احتفظ بسر webhook طيّ الكتمان. قم بتدويره دوريًا وحدّث منطق التحقق الخاص بك فور التدوير. لا تكشف عنه أبدًا في الكود الخاص بالعميل أو المستودعات العامة.

ملاحظات مهمة

يجب أن يكون عنوان URL لنقطتك النهائية عنوان HTTPS POST يمكن الوصول إليه علنًا.
إذا كانت نقطتك النهائية غير متاحة مؤقتًا، تحقق من لوحة السجل الخاصة بـ webhook في AgencyHandy — يمكنك إعادة تسليم أي حدث سابق مباشرةً من هناك.
راقب نشاط webhook بانتظام للكشف عن عمليات التسليم الفاشلة أو محاولات الوصول غير المصرح به.
قد تُوقِف AgencyHandy Webhooks التي تفشل بشكل متكرر — راجع سجلات التسليم للكشف عن المشكلات مبكرًا.

ابدأ الآن

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

CRM

الخدمات والطلبات

العروض والفواتير

الفريق والمهام

النماذج والملفات

الحساب والفوترة

المدفوعات

التكاملات

إدارة Webhooks: الإنشاء والاختبار والمصادقة

الأحداث المدعومة

إنشاء webhook

اختبار webhook

مصادقة حمولات webhook

ترويسة التوقيع

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

ملاحظات مهمة

​الأحداث المدعومة

​إنشاء webhook

​اختبار webhook

​مصادقة حمولات webhook

​ترويسة التوقيع

​التحقق من توقيع webhook

​ملاحظات مهمة

الأحداث المدعومة

إنشاء webhook

اختبار webhook

مصادقة حمولات webhook

ترويسة التوقيع

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

ملاحظات مهمة