التكاملات: Webhooks الصادرة

ترسل الإعدادات ← التكاملات (العنوان ‎/app/settings/integrations) أحداث مساحة العمل هذه إلى عنوان URL خاص بك، مثل أداة أتمتة (Zapier أو Make أو n8n) أو خادمك. لا يراها ويغيّرها إلا مالك ومسؤول.

خطوة بخطوة: إضافة نقطة اتصال

1. افتح الإعدادات ← التكاملات.
2. في رابط نقطة الاتصال اكتب عنوان نقطة الاتصال، مثل https://your-system.example.com/omnibrand-hook. يجب أن يكون https وأن يكون متاحًا على الإنترنت العام؛ وإلا يذكر سطر أحمر السبب ("يجب أن يبدأ عنوان نقطة الاتصال بـ https://. لا يُقبل http://."، أو أنه لا يمكن الوصول إليه من الإنترنت).
3. تحت الأحداث حدّد الأحداث التي تستقبلها نقطة الاتصال. لكل خانة وصف واضح واسم الحدث، مثل post.published ("نُشر منشور") وpost.failed وsocial_account.token_expired وsocial_account.disconnected؛ وكل الأحداث، بما فيها ما يُضاف لاحقًا هو *. وworkspace.created وinvitation.accepted موجودان أيضًا. حدّد حدثًا واحدًا على الأقل، وإلا يقول النموذج "اختر حدثًا واحدًا على الأقل."
4. انقر إضافة نقطة اتصال.
5. يظهر مفتاح التوقيع (انسخه الآن - لن يظهر مرة أخرى): مع المفتاح فوق النموذج، وتنتقل الصفحة إليه لتراه على الهاتف أيضًا. وإن رُفضت نقطة الاتصال تظهر الرسالة الحمراء في المكان نفسه وتنتقل الصفحة إليها. انسخ المفتاح إلى نظامك المستقبِل الآن؛ فلن يعرضه OmniBrand مجددًا (سوى آخر أربعة أحرف). وينسخه لك زر نسخ المفتاح بجانبه.
6. انقر إرسال اختبار على نقطة الاتصال. ترى ✓ تم التسليم مع رمز HTTP الذي أعاده خادمك. وعند الفشل ترى "لم يُسلَّم: ردّ خادمك بـ [الحالة]." مع ما يجب إصلاحه، مثل 405 Method Not Allowed "يجب أن يقبل طلبات POST على هذا العنوان."، و404 Not Found "لا شيء يرد على هذا العنوان. تحقق من الرابط."، ولإعادة التوجيه "أعاد التوجيه إلى عنوان آخر، ولا تتبع الـWebhooks إعادة التوجيه أبدًا. سجّل العنوان النهائي بدلًا منه."؛ أو إن تعذر الوصول إلى الخادم أصلًا "لم يُسلَّم: تعذر الوصول إلى خادمك ([السبب]). تحقق من الرابط ومن أن الخادم يعمل." ويفتح رابط كيف تعمل الـWebhooks هذا المقال.

كل نقطة اتصال

• العنوان وشارة نشط أو معطّل.
• «الأحداث: … · المفتاح ••••1234» وكل حدث بوصفه (مثل «نُشر منشور»)، ومعها «· N محاولات فاشلة متتالية» حين تفشل محاولات التسليم، و«· N بانتظار إعادة المحاولة» حين تنتظر أحداث محاولتها التالية.
• سطر أحمر «N عمليات تسليم فاشلة - افتح سجل التسليم لإرسالها مرة أخرى.» حين تتوقف المحاولات لأحداث (انظر سجل التسليم وإعادة الإرسال أدناه).
• المفتاح مفعّل / معطّل يوقف التسليم أو يستأنفه. وأثناء حفظ التغيير تقول البطاقة "جارٍ العمل…" وينتظر زرا إرسال اختبار وحذف؛ وإن فشل المفتاح أو حذف يظهر السبب بالأحمر أسفل بطاقة نقطة الاتصال نفسها وتنتقل الصفحة إليه.
• إرسال اختبار يرسل حدثًا اسمه webhook.test مرة واحدة (لا يُعاد ولا يُحفظ في السجل).
• سجل التسليم يعرض عمليات التسليم الأخيرة لنقطة الاتصال (ويغلقها زر إخفاء سجل التسليم).
• حذف يسأل "هل تريد حذف الـ webhook المرسل إلى (العنوان)؟ يتوقف إرسال الأحداث إليه فورًا ويضيع مفتاح التوقيع نهائيًا. لإيقافه مؤقتًا بدلًا من ذلك، أطفئ مفتاح التشغيل الخاص به." عنوان النافذة حذف نقطة الاتصال؟؛ انقر حذف لإزالة نقطة الاتصال فورًا، أو إلغاء للإبقاء عليها.

ما يستقبله خادمك

طلب POST بمحتوى JSON: id (معرّف الحدث - استخدمه لتجاهل التكرار)، وevent (مثل post.published)، وoccurredAt، وdata (تفاصيل الحدث). والترويسات:

• X-OmniBrand-Signature: ‏sha256= متبوعًا بـHMAC-SHA256 للمحتوى الخام بمفتاح التوقيع.
• X-OmniBrand-Timestamp وX-OmniBrand-Signature-V2: ‏HMAC-SHA256 للطابع الزمني ثم نقطة ثم المحتوى - استخدمه لرفض الطلبات القديمة المُعادة.

أجب بأي رمز 2xx خلال 5 ثوانٍ.

إعادة المحاولة: إلى متى يواصل OmniBrand المحاولة

يُحفظ كل حدث قبل إرساله، فلا يضيع شيء إن أُعيد تشغيل خادمك أو خادمنا. وحين لا يرد خادمك برمز 2xx خلال 5 ثوانٍ (خطأ، أو انتهاء المهلة، أو إعادة توجيه، أو أي رد غير 2xx) يُعاد إرسال الحدث بعد نحو دقيقة، ثم 5 دقائق، و15 دقيقة، و30 دقيقة، وساعة، وساعتين، و4 ساعات، و8 ساعات، و12 ساعة - 10 محاولات خلال نحو 28 ساعة. وتختلف كل مدة بما يصل إلى 20% حتى لا تصل المحاولات كلها معًا. ولأن المحاولة المعادة قد تصل بعد حدث لاحق، استخدم id لتجاهل التكرار وoccurredAt لترتيب الأحداث.

وإن فشلت المحاولات العشر كلها يُعلَّم التسليم فشل ويبقى في السجل 30 يومًا، ويمكنك إرساله مرة أخرى.

سجل التسليم وإعادة الإرسال

1. على نقطة الاتصال انقر سجل التسليم. تعرض عمليات التسليم الأخيرة آخر 30 يومًا، الأحدث أولًا.
2. يعرض كل صف شارة الحالة - تم التسليم أو جارٍ إعادة المحاولة أو فشل - واسم الحدث ووقته و«المحاولة N من 10»، ولما هو جارٍ إعادة المحاولة وقت «المحاولة التالية»، ولما لم يصل «آخر رد:» مع ما ردّ به خادمك (مثل «HTTP 503» أو «No answer within 5 s»).
3. حدّد الفاشلة فقط لعرض الفاشلة وحدها؛ ويحمّل عرض الأقدم المزيد. وإن لم توجد يظهر «لا توجد عمليات تسليم فاشلة خلال آخر 30 يومًا. ولا تُعدّ عمليات التسليم التي ما زالت تُعاد محاولتها فاشلة.» (التسليم جارٍ إعادة المحاولة لم يفشل بعد).
4. لإرسال حدث مرة أخرى انقر إعادة الإرسال في صفه. يُرسل فورًا: ترى «تم التسليم.» أو «لم يتم التسليم بعد (الرد). ستُعاد المحاولة تلقائيًا.» - ويبدأ الحدث المعاد إرساله 10 محاولات جديدة.
5. لإرسالها كلها بعد إصلاح خادمك انقر إعادة إرسال كل الفاشلة (يظهر حين توجد عمليات تسليم فاشلة). ترى «أُضيفت N عمليات تسليم فاشلة إلى قائمة الانتظار وستُرسل خلال دقيقة.»

تحتاج إعادة الإرسال إلى نقطة اتصال مفعّلة؛ وما دامت معطّل تنتظر الأزرار ويقول السجل «نقطة الاتصال هذه معطّلة. شغّل مفتاحها لإعادة الإرسال.» والأحداث التي تقع أثناء تعطيل نقطة الاتصال لا تُرسل ولا تُحفظ.

إذا حدث خطأ

• لا تُتبع عمليات إعادة التوجيه أبدًا؛ سجّل العنوان النهائي. وإن كان عنوانك يعيد التوجيه يقول الاختبار "لم يُسلَّم: ردّ خادمك بـ 301 Moved Permanently. أعاد التوجيه إلى عنوان آخر، ولا تتبع الـWebhooks إعادة التوجيه أبدًا. سجّل العنوان النهائي بدلًا منه." (مع الحالة التي أرسلها خادمك).
• حين تفشل كل محاولات التسليم إلى نقطة اتصال طوال يوم كامل (20 محاولة متتالية على الأقل) تتحول تلقائيًا إلى معطّل ويُبلَّغ المسؤولون، وتُعلَّم عمليات التسليم المنتظرة فشل. أصلح المستقبِل ثم أعد المفتاح إلى مفعّل، وافتح سجل التسليم وانقر إعادة إرسال كل الفاشلة.

الوصول إلى API (للمطورين)

في أسفل الصفحة بطاقة الوصول إلى API (للمطورين): "اربط OmniBrand بأنظمتك أو Zapier أو Make لإنشاء المنشورات وإضافة جهات الاتصال وقراءة التحليلات تلقائيًا." في باقتي الوكالات والمؤسسات تضم مفاتيح API لواجهة API العامة (انظر الوصول إلى API). وفي الباقات الأخرى تقول "الوصول إلى API متاح في باقة الوكالات." مع رابط عرض الباقات. أما الـ Webhooks في هذه الصفحة فتعمل في كل الباقات.

معلومات مفيدة

• تستقبل نقطة الاتصال أحداث مساحة العمل هذه فقط، إضافة إلى أحداث الحساب كله (الفوترة والحساب).
• تتبع نقطة الاتصال مساحة العمل التي كنت فيها عند إضافتها.