ما هو Webhook؟
يتيح لك Webhook أن تُبلَّغ عند حدوث إجراءات نظام معينة عبر استدعاء لعنوان URL توفره أنت. تُعرف webhooks أيضًا باسم “URL Callbacks” أو “HTTP push calls”. يجب أن يستخدم عنوان URL الخاص بك SSL وأن يبدأ بـ HTTPS.Webhook Actions
اطلع على الإجراءات المتاحة لـ webhooks.
فهم Webhooks في Ayrshare
يتم تصنيف webhooks حسب الإجراء المحدد و_تُسجَّل على مستوى Primary Profile أو User Profile_. تُرسل أي تحديثات لـ Primary أو User Profiles أولاً إلى Webhook المُسجَّل لـ User Profile. إذا لم يكن لدى User Profile Webhook مُسجَّل، فسيتم إرسال التحديث إلى Webhook المُسجَّل لـ Primary Profile. على سبيل المثال:- إذا كان لدى User Profile Social Action Webhook مُسجَّل وقام بإلغاء ربط TikTok، فسيتم استدعاء عنوان URL الخاص بـ Social Action Webhook المُسجَّل لـ User Profile. لن يتم استدعاء webhook الخاص بـ Primary Profile.
- إذا قام User Profile بإلغاء ربط TikTok و_لم_ يكن لديه Social Action Webhook مُسجَّل، ولكن Primary Profile يمتلك Webhook مُسجَّلًا، فسيتم استدعاء عنوان URL الخاص بـ Social Action Webhook المُسجَّل لـ Primary Profile.
تسجيل Webhook
قم بتسجيل Webhook من خلال توفير عنوان URL لنقطة نهاية ونوع الإجراء لنقطة النهاية POST/hook/webhook. عندما يحدث الإجراء، سيتم إرسال رسالة HTTP POST إلى عنوان URL المُقدَّم.
مثال: تسجيل عنوان URL للحصول على إشعار بحالة منشور مجدول.
يجب ألا يستخدم عنوان URL لنقطة نهاية Webhook إعادة توجيه ويجب أن يكون عنوان URL الوجهة النهائي.
إذا قمت بتسجيل webhook لـ Primary Profile فقط، فستقوم User Profiles تلقائيًا بوراثة webhook الخاص بـ Primary Profile.
للحصول على webhook فريد لكل User Profile، يجب عليك تسجيل webhook لكل User Profile.
بعد أن يستقبل Webhook الخاص بك
HTTP POST، يجب أن يستجيب خادمك
بحالة HTTP 200 لوضع علامة على المكالمة كناجحة. إذا لم يستجب خادمك
خلال 15 ثانية، تُسجَّل المحاولة كفاشلة وتُعاد. استجب فور استلام
الطلب ونفّذ المعالجة بشكل غير متزامن — انتهاء المهلة ليس رفضًا،
لذا إذا أكمل معالجك العمل لكنه أجاب متأخرًا، ستدفعك إعادة المحاولة
إلى معالجته مرتين.إعادة محاولات Webhook
تعتمد إعادة محاولة أي عملية تسليم فاشلة على كيفية فشلها. تحمل كل إعادة محاولة نفسhookId. ويُعاد بناء الحمولة في كل محاولة، لذا قد يختلف timeStamp — والتوقيع عليه.
تُعاد المحاولة — الأعطال المؤقتة. استجابة 429 أو 408 أو 425، وأي 5xx، وانتهاء المهلة، وانقطاع الاتصال — تحصل على 9 محاولات إرسال كحد أقصى على مدى ساعة تقريبًا — الإرسال الأول زائد 8 إعادات. وإذا استمر الفشل بعد ذلك، تُحاول عملية التسليم مرة أخرى وفق جدول متباعد — بعد نحو 5 دقائق و30 دقيقة وساعتين و12 ساعة. لذلك قد تصل عملية التسليم بعد نحو 16 ساعة من الحدث الأصلي.
لا تُعاد المحاولة — حالات الرفض. أي استجابة 4xx أخرى، مثل 400 أو 401 أو 403 أو 404 أو 410، تُعتبر نهائية من المحاولة الأولى. فهي تعني أن الطلب نفسه قد رُفض، وتكراره لن يغيّر النتيجة.
دلالات التسليم ومنع الازدواج (Idempotency)
تُسلِّم Ayrshare webhooks مرة واحدة على الأقل. التكرارات العرضية هي سلوك تشغيلي طبيعي وليست خللًا — يحتاج كل مستهلك إلى منع الازدواج (idempotency) بوصفه خاصية دائمة. تصل التكرارات بشكلين مختلفين، ويحتاج كل منهما إلى مفتاح مختلف:
يُعرِّف
hookId تسليمًا واحدًا لحدث. وهو متطابق في كل إعادة محاولة لهذا التسليم، لذا فإن الاستحواذ عليه يجعل إعادة المحاولات آمنة — لكن إشعارًا جديدًا للحدث الأساسي نفسه يصل بـ hookId جديد، لذا فإن hookId وحده لن يتعرف على هذه الحالة.
نمط المستقبل الموصى به:
- استجب أولاً. أرجع
2xxفورًا، ثم عالج بشكل غير متزامن. انتهاء المهلة ليس رفضًا — إذا أنهيت العمل لكنك أجبت متأخرًا، فسيُرسل الحدث مرة أخرى. - استحوذ على
hookIdبشكل ذري (atomic) لحظة وصول الطلب — قيد فريد، أوINSERT ... ON CONFLICT DO NOTHING، أوSET NX— وليس فحصًا يليه كتابة. يمكن أن تصل محاولتان بشكل متزامن، ويسمح حاجز الفحص-ثم-التنفيذ لكلتيهما بالمرور. - استحوذ على مفتاح خاص بك أيضًا، مبني من الحمولة، حتى يظل إشعار ثانٍ يحمل
hookIdجديدًا معروفًا. فيmessages، يعملidمجتمعًا معsubActionبشكل جيد. - بعد ذلك نفّذ العمل، مع الاحتفاظ بكلا الاستحواذين لفترة كافية لتغطية نافذة إعادة المحاولة وأي إعادة إشعار لاحقة. بما أن إعادة المحاولة قد تصل بعد نحو 16 ساعة، احتفظ بالاستحواذين لمدة 24 ساعة على الأقل. الاستحواذ الذي تنتهي صلاحيته قبل ذلك لن يتعرّف على إعادة محاولة متأخرة، وستعالج الحدث نفسه مرتين.
إن
id في الحمولة ليس فريدًا بمفرده لكل نوع من الأحداث — يتكرر مُعرِّف
الرسالة نفسه عبر التعديلات والتفاعلات، ولا تحمل حمولات messageRead
أي id — لذا اجمعه مع subAction بدلًا من استخدامه مجردًا.ترويسات بيانات التسليم الوصفية
يحمل كل تسليم ترويستين تحددان تلك الإرسالية المحددة، بحيث يمكنك التمييز بين الأصل وإعادة المحاولة:X-Ayrshare-Delivery-Attempt هي 0 عند الإرسال الأول وتزيد بمقدار واحد في كل إعادة محاولة، لذا فإن أي قيمة أعلى من 0 تعني أننا أرسلنا هذا التسليم مرة واحدة على الأقل مسبقًا. تعامل معها بوصفها عدّادًا غير محدود بدلًا من مجموعة قيم ثابتة — عدد إعادات المحاولة تفصيل تشغيلي قابل للتغيير. أما X-Ayrshare-Delivery-Id فهو فريد لكل محاولة — اذكره للدعم وسيحدد سجل التسليم بدقة.
تحدد هاتان الترويستان الإرسالية؛ بينما يحدد hookId الحدث. قم بمنع الازدواج بناءً على hookId، وليس على مُعرِّف التسليم — فمُعرِّف التسليم مختلف في كل محاولة بحسب التصميم، لذا لن يُتعرَّف على أي شيء بوصفه تكرارًا.
أمان Webhook
يمكنك اختيار إضافة أمان إضافي عن طريق تعيين مصادقة HMAC كطلب HTTP. يتم ذلك غالبًا لمنع هجمات replay. تستخدم Ayrshare HMAC-SHA256 لتجزئة نص الرسالة وتتضمنها والطابع الزمني UNIX في رأس POST.X-Authorization-Content-SHA256 مع HMAC-SHA256 لنص POST. المفتاح السري للتوقيع يعمل على مستوى الملف الشخصي — مفتاح سري واحد لكل User Profile، يُستخدم عبر جميع إجراءات webhook الخاصة بذلك الملف الشخصي، لذا فإن تعيينه لإجراء واحد يغيّره لجميع الإجراءات على هذا الملف الشخصي. تدير الحسابات متعددة الملفات الشخصية مفتاحًا سريًا منفصلًا لكل ملف شخصي (استهدف ملفًا شخصيًا باستخدام ترويسة Profile-Key).