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

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

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

​
إنشاء webhook

1

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

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

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

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

إنشاء webhook جديد

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

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

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

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

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

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

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

تفعيل webhook

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

حفظ التكوين

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

​
اختبار webhook

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

فتح webhook

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

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

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

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

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

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

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

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

تحقق من نظامك الخارجي للتأكد من وصول حمولة الاختبار ومعالجتها كما هو متوقع. في 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
​
webhookId
string
مطلوب
معرّف webhook الذي استقبل الحدث. ابحث عنه في صفحة تفاصيل webhook في AgencyHandy.
​
signature
string
مطلوب
قيمة ترويسة x-ah-sig من طلب webhook الوارد.
​
secret
string
مطلوب
السر الخاص بـ webhook المعروض في صفحة تفاصيله في AgencyHandy.
​
payload
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" }
الاستجابات
​
verification_status
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 التي تفشل بشكل متكرر — راجع سجلات التسليم للكشف عن المشكلات مبكرًا.