الويب هوك

الويب هوك جرس باب يضغطه نظام آخر فيرسل Botragon رسالة إلى أحد عملائك. اتجاهه إلى Botragon لا منه، وهذه الصفحة تقول لك كيف تبنيه، وكيف تقفله، وكيف تقرأ السطر الأحمر يوم يُخفق.

---

ما الذي يفعله الويب هوك في Botragon؟

يمنحك الويب هوك عنوانًا واحدًا على الإنترنت. ونظام آخر تملكه أصلًا — تطبيق شركة الشحن، أو شاشة المطبخ، أو برنامج المواعيد، أو نظام المحاسبة، أو Zapier — يرسل إلى هذا العنوان بضعة أسطر من JSON. فيقرأ Botragon هذه الأسطر، ويعثر على العميل الذي تسمّيه (أو ينشئه)، ويرسل إليه قالب واتساب أو بريدًا إلكترونيًا. لا أحد يفتح Botragon، ولا تعمل أي أتمتة.

والمنتج يقولها بكلماته هو، في لوحة «كيف يعمل الويب هوك» أسفل القائمة:

«يمنحك كل ويب هوك رابطًا خاصًا به. أرسل حمولة JSON عبر POST، فيعثر Botragon على جهة الاتصال (أو ينشئها) ويرسل إليها قالب واتساب أو بريدًا إلكترونيًا — دون أي مسار. أما الاختبار فيتم داخل صفحة إعدادات كل ويب هوك، لا من هذه القائمة.»

اقرأ هذه الجملة مرتين، فالعنوان الذي فوقها قد يضلّلك. تقول مقدمة الصفحة: «استقبل الأحداث من نظام إدارة العملاء أو المتجر أو أي مصدر آخر — وردّ عبر قالب واتساب أو البريد الإلكتروني. دون الحاجة إلى أي مسار.» وكلمة «الأحداث» هي التي تجعل القارئ ينتظر قائمة بما يجري داخل Botragon ليشترك فيها — تدفّقًا يغذّي لوحته هو. لا توجد هذه القائمة ولا هذا التدفّق. Botragon لا ينادي نظامك أبدًا. نظامك هو الذي ينادي Botragon.

وانتبه لكلمة «مسار» على هذه الشاشة، فهي تحمل معنيين متجاورين: عمود «المسار» في القائمة هو مقطع الرابط الذي يناديه نظامك، أما «دون أي مسار» في التعريف فتعني أن لا أتمتة تعمل خلف الرسالة.

مخبز الأصالة، الرياض. يبيع كعك المناسبات عبر Salla، ويأخذ طلبات خاصة عبر واتساب. حين تجهز الكعكة، يضغط الخبّاز «جاهزة» على شاشة صغيرة في المطبخ — لا في Salla ولا في Botragon. واليوم يترك أحدهم عمله ليتّصل بالعميلة، وفي عصر الخميس تتأخّر هذه المكالمة ساعة كاملة.

فبنى المخبز ويب هوك واحدًا، سمّاه Cake ready for pickup. صارت شاشة المطبخ ترسل إلى Botragon بضعة أسطر فيها رقم العميلة ومرجع الطلب، فتصل الرسالة لحظة إغلاق العلبة — أما على واتساب فهذه الخطوة الأخيرة بانتظار موافقة المنصّة، ما لم يربط المخبز بتطبيق Meta الخاص به. ويب هوك واحد، ولحظة إطلاق تعيش فعلًا خارج كل ميزة أخرى في Botragon.

ثلاث حقائق قبل أن تنفق على هذا أمسية

صفحة الإعداد بالإنجليزية في معظمها. لك أن تتصفّح الويب هوك بالعربية، ولك أن تنشئه بالعربية. فإذا وصلت إلى صفحة إعدادات ذلك الويب هوك، صار كل عنوان وكل حقل وكل زر وكل تحذير وكل رسالة خطأ بالإنجليزية — في اللغتين معًا، وهي الصفحة التي يجري فيها العمل كله. والاستثناء الوحيد اليوم كتلة المفتاح المشترك في القسم 5، فقد صارت تتكلم العربية: «هناك مفتاح مشترك مفعّل.» و«إنشاء مفتاح جديد». أما ما حولها — "Security" و"Security mode" و"Header name" — فما زال بالإنجليزية. ولهذا تجد أسماء الحقول في هذه الوثيقة بالإنجليزية كما تراها على الشاشة تمامًا، ومعناها بالعربية بين قوسين. لا تبحث عن اسم عربي هناك — لن تجده.

لم توافق Meta على Botragon بعد. ولا يمكن ربط واتساب وإنستغرام وماسنجر عبر مسار المنصّة اليوم. وقائمة البدء تقولها بصراحة بدل أن تعرض عليك زرًّا: «واتساب وإنستغرام وماسنجر — بانتظار موافقة المنصّة». وواتساب هو طريقة الإرسال الافتراضية لكل ويب هوك جديد، ولن يُفعَّل ويب هوك واتساب من غير رقم مربوط وقالب معتمد من Meta. فاليوم: البريد الإلكتروني يعمل من أوله إلى آخره. أما واتساب فلا يعمل إلا إن ربطت بتطبيق Meta الخاص بك — راجع صفحة الربط بواتساب عبر تطبيق Meta الخاص بك.

والإرسال المخفق لا يُعاد أبدًا. يحاول Botragon مرة واحدة. فإن أخفق، كتب سطرًا واحدًا في السجلّ وتوقّف. لا طابور، ولا محاولة ثانية، ولا زر إعادة تشغيل في أي موضع من الشاشة. الإرسال المخفق عميل لم تصله رسالتك ولن تصله. لا شيء في المنتج يخبرك بهذا، ولذلك تتكرّر الجملة في هذه الصفحة ثلاث مرات.

---

ما الذي تحتاجه قبل أن يعمل الويب هوك؟

هذه شاشة للمدير وحده. ترفض القائمة وصفحة الإعدادات معًا أن تُفتح للمشرف أو موظف الدعم أو المشاهد. فإن قال لك زميل إن الرابط لا يفعل عنده شيئًا، فتحقّق من صلاحيته قبل أن تتحقّق من أي شيء آخر.

لك بوت واحد على الأقل. القائمة مرشَّحة بالبوت، وكل ويب هوك يخصّ بوتًا واحدًا. ومن غير بوت تقول الشاشة «أنشئ بوتًا أولًا.»، ويبقى زر «＋ ويب هوك جديد» معطّلًا. ولا يُشارَك ويب هوك واحد بين بوتين — فإن أردت الجرس نفسه على بوت ثانٍ، بنيته من جديد.

للإرسال بالبريد الإلكتروني: مُرسِل بريد مُعدّ. موضعه الإعدادات ← «مزوّد البريد الإلكتروني». ومن غيره يرجع Botragon إلى مُرسِل مساحة العمل الافتراضي، ولا توجد في المنتج أي شاشة تُريك بريد المرسِل الذي سيقرأه عميلك فعلًا.

للإرسال عبر واتساب: أمران على ذلك البوت. رقم واتساب مربوط وفعّال، وقالب رسالة معتمد من Meta. يُفحص الاثنان حين تضغط "Activate"، ويُعاد فحصهما مع كل إطلاق للويب هوك. وهنا تضرب فجوة موافقة Meta — وأكثر مساحات العمل اليوم لا تملك أيًّا منهما.

ولا يُفحص شيء في باقتك عند إنشاء الويب هوك ولا عند تفعيله.

وتحتاج من يجعل نظامك الآخر يرسل JSON. غالبًا مطوّر بالساعة، أو ساعة من وقته، أو خطوة في Zapier. هذه ميزة لا تكتمل من داخل Botragon وحده.

---

ما خياراتك في الويب هوك؟

في نافذة «ويب هوك جديد»

في صفحة إعدادات الويب هوك

أسماء الحقول أدناه هي ما تراه على الشاشة حرفًا بحرف — بالإنجليزية — ومعناها بالعربية بين قوسين.

أمران ستبحث عنهما ولن تجدهما. "HTTP method" معروض بقيمة ثابتة "POST · Fixed" ولا خيار فيه. وقائمة الإعداد ستحمل تحذيرًا نصّه "Create-if-missing is off — unknown contacts will not be auto-created." بلا أي مفتاح في المنتج كلّه لتشغيله. تجاهله: يُنشئ Botragon جهة الاتصال على كل حال حين يكون الرقم أو البريد جديدًا، والتحذير لا يمنع التفعيل.

---

كيف تبني ويب هوك في Botragon؟

نبني ويب هوك واتساب لمخبز الأصالة. ومن الخطوة 7 فصاعدًا كل شاشة بالإنجليزية، مهما كانت لغة لوحتك.

1. افتح «الإعدادات» (آخر عنصر في الشريط الجانبي)، ثم «البوت والربط»، ثم «الربط مع أنظمتك».
2. من مرشّح «لـ:»، اختر البوت الذي يخصّه هذا الويب هوك.
3. اضغط «＋ ويب هوك جديد».
4. في «الاسم»، اكتب اللحظة التي تطلقه — Cake ready for pickup.
5. في «طريقة الإرسال»، اختر «قالب واتساب» (أو «بريد إلكتروني»، وهو ما يعمل اليوم من غير تطبيق Meta خاص بك).
6. اضغط «إنشاء ومتابعة». يقرأ الزر «جارٍ الإنشاء…» ريثما يعمل، ثم يقول التنبيه «تم إنشاء الويب هوك»، ويفتح لك Botragon صفحة الإعدادات.
7. في القسم 1، "Webhook URL"، اضغط "Generate" ليُولَّد مقطع الرابط.
8. اضغط "Copy URL" والصق العنوان في مكان آمن — يؤكّد التنبيه «تم نسخ الرابط».
9. في القسم 2، "Payload JSON Shape"، الصق رسالة حقيقية واحدة من نظامك الآخر في "Sample payload". تمتلئ لوحة "Detected fields" إلى جانبها.
10. في القسم 3، "Find or Create Contact"، اضبط "Identifier field" على الحقل الذي يحمل رقم هاتف العميل.
11. في القسم 4، "Choose What Botragon Sends"، اختر رقمك من "WhatsApp channel".
12. اختر رسالتك المعتمدة من قائمة القوالب.
13. وجّه كل خانة من خانات القالب إلى حقل من الحمولة.
14. في القسم 5، "Security"، اقرأ السطر تحت "Header name". الويب هوك الذي تنشئه اليوم يولد ومعه مفتاح مشترك مضبوط سلفًا، والشاشة تقول ذلك بالعربية: «هناك مفتاح مشترك مفعّل.»
15. وإن كان الويب هوك جديدًا، فقد ظهر لك المفتاح مرة واحدة لحظة إنشائه، تحت عنوان «احفظ هذا المفتاح الآن» — «هذه هي المرة الوحيدة التي يظهر فيها». انسخه حينها بزرّ «نسخ المفتاح»، وسلّمه إلى من يبني الطرف المنادي.
16. وإن لم تحفظه، فلا سبيل إلى استرجاعه. اضغط «إنشاء مفتاح جديد»، واحفظ القيمة الجديدة، وسلّمها بدلًا من الأولى — ويتوقف المفتاح القديم عن العمل فورًا.
17. اضغط "Save". يقرأ التنبيه "Saved as draft" — وهذا لا يُنزل ويب هوك عاملًا عن الخدمة، إنما يحفظ تعديلاتك.
18. اضغط "Test Webhook" لتمرير رسالتك التجريبية تمريرًا حقيقيًا.
19. اضغط "Activate".

الأمر الوحيد الذي يجب ضبطه. المفتاح يظهر مرة واحدة ولا يظهر بعدها أبدًا. والشاشة تقولها بكلماتها هي: «ظهر مرة واحدة عند إنشائه ولا يمكن عرضه مرة أخرى. أنشئ مفتاحًا جديدًا إن فقدته — ويتوقف القديم عن العمل فورًا.» ولا يوجد في هذه الشاشة زرّ لنسخ المفتاح، لأنه لم يبقَ شيء يُنسخ. فإن ضاعت منك القيمة فليس أمامك إلا «إنشاء مفتاح جديد» — وهو يسري في الحال، فيبدأ كل من لا يزال يرسل المفتاح القديم بالإخفاق فورًا، بلا إشعار وبلا إعادة محاولة. لا تنشئ مفتاحًا جديدًا إلا ومعك من يحدّث الطرف المنادي في الدقيقة نفسها.

لمطوّرك

كل ما في هذه الفقرة ثابت في Botragon ولا يُضبط من أي موضع في المنتج.

• يرسل نظامك الآخر POST إلى العنوان الظاهر في "Generated URL"، وجسمه JSON.
• إن فعّلت "Shared secret header"، فالسرّ يذهب في الترويسة X-Botragon-Webhook-Secret. تجاهل حقل "Header name" في شاشة Botragon — قيمته تُحفظ ولا تُقرأ. هذا الاسم وحده هو الذي يعمل.
• يردّ Botragon بـ 200 ومعه {"success":true,…} حين أرسل الرسالة، وبـ 422 ومعه {"success":false,…,"error":"…"} حين لم يرسلها. أما المسار المجهول فيردّ 404 عاريًا بجسم فارغ — ولا يكتب سطرًا في السجلّ إطلاقًا، فخطأ إملائي في العنوان لا يُرى من داخل Botragon.
• ولا توجد إعادة محاولة. محاولة واحدة، وسطر سجلّ واحد، وانتهى. إن أردت للرسالة أن تنجو من إخفاق عابر، فأعِد المحاولة على الـ 422 بنفسك. لن يفعلها Botragon عنك.
• الحقول تُسمّى بمسار منقوط داخل JSON — customer.phone، order.ref. وما تكتبه في Botragon يجب أن يطابق الرسالة الحيّة، لا العيّنة.
• يحتفظ السجلّ بآخر "Latest 10" محاولات، بلا رجوع إلى ما قبلها وبلا تصدير.

---

كيف تعرف أن الويب هوك قد عمل؟

تنقلب الشارة بجانب اسم الويب هوك إلى "Active"، وتستبدل قائمة الإعداد الملتصقة على الجانب صندوقها الأحمر بصندوق أخضر عنوانه "Active" ونصّه "Webhook is receiving live POSTs.". وقبل التفعيل، يقرأ الصندوق نفسه "All checks passed" وتحته "Ready to activate.".

وفي القائمة، يعرض عمود «الحالة» للسطر «مفعّل»، ويتحوّل آخر أزراره من «تفعيل» إلى «إيقاف»، ويكفّ عمود «آخر تشغيل» عن قول «لم يُشغَّل بعد» ويبدأ بعرض وقت.

وأول رسالة حقيقية تنزل في القسم 7، "Trigger History"، الموسوم "Latest 10". والسطر الجيّد سطر أخضر "Success" يحمل معرّف العميل وطريقة الإرسال ومرجعًا. وقبل أن يُطلق شيء قط، يقرأ ذلك القسم "No trigger attempts yet" مع الدفعة "Hit Test Webhook above, or fire a real POST to your webhook URL."

وإشارتا نجاح لا تثق بهما. في "Inline Test Result"، يقرأ سطر "Contact / Found" دائمًا "Found" في ويب هوك البريد الإلكتروني، سواء وُجد سجلّ جهة اتصال أم لم يوجد — هو سطر تجميلي هناك. والشارة الخضراء "Created" بجانبه موصوفة في الشيفرة نفسها بأنها تقديرية، فلا تقرأها دليلًا.

وشيء ستبحث عنه ولن تجده: الرسالة التي يرسلها الويب هوك لا تظهر في صندوق الوارد. ليست في محادثة ذلك العميل، وهذا بحكم التصميم. وسجلّ "Trigger History" الخاص بالويب هوك هو الأثر الوحيد على أنها حدثت.

---

لماذا يُخفق الويب هوك؟

زرّ "Activate" معطّل

تضغط "Activate" فلا يحدث شيء، أو لا يقبل الزرّ ضغطتك أصلًا. مرّر المؤشّر فوقه فيقول التلميح "Fix 2 errors before activating". وقائمة الإعداد على الجانب تحمل صندوقًا أحمر عنوانه "Activation blocked" ونصّه "Fix 2 errors before activating. Save remains allowed." وتحته كل سبب مسرودًا. وإن بلغت الخادم، جاء عنوان التنبيه رمزًا عاريًا: ACTIVATION_BLOCKED. هذا مقصود ولا يُترجَم في أي لغة — إنه قيمة قصيرة تلصقها في تذكرة الدعم.

لماذا: شيء مطلوب لا يزال فارغًا، ولن يضع Botragon ويب هوك نصف مبنيّ على عنوان عام. والأسباب منقولة كما هي، سببًا في كل سطر: "Webhook path is required" · "Identifier field is required" · "WhatsApp channel is required" · "Approved WhatsApp template is required" · "WhatsApp template has 1 unmapped placeholder(s)" · "To payload path is required" · "Email subject is required" · "Email body is required" · وإن كتبت الحقل بيدك: Identifier "customer.phone" is not in the detected fields. Pick from the list or enable Advanced.

ما تفعله: اضغط أي سطر في القائمة فينزلق بك إلى القسم صاحبه. أصلحها بالترتيب فيخضرّ الصندوق الأحمر. وإن كان المانع "Approved WhatsApp template is required" أو "WhatsApp channel is required"، فتلك فجوة موافقة Meta لا خطأ منك — حوّل الويب هوك إلى «بريد إلكتروني»، أو اربط واتساب بتطبيق Meta الخاص بك.

الويب هوك «مفعّل» والعميل لم يصله شيء

افتح القسم 7، "Trigger History". عندك سطر أحمر "Failed"، وخانة الخطأ فيه تقرأ Identifier field "customer.phone" not found in payload.

لماذا: العيّنة التي لصقتها قالت إن الرقم في customer.phone، والرسالة الحيّة تضعه في موضع آخر — customer.mobile، أو contact.phone_number، أو طبقة أعمق. نظر Botragon حيث دللته تمامًا، فلم يجد شيئًا، فتوقّف. هذا أكثر إخفاق يقع في هذه الميزة على الإنتاج، وهو لا يعلن عن نفسه: لا تنبيه، ولا بريد، ولا شيء سوى سطر أحمر في صفحة لا يراقبها أحد.

ما تفعله: اضغط "View" على ذلك السطر لتقرأ ما أرسله نظامك فعلًا، وصحّح "Identifier field" في القسم 3 ليطابقه، ثم اضغط "Save". ثم تذكّر أهم جملة في هذه الصفحة: ذلك العميل لم تصله رسالتك ولن تصله. لا إعادة محاولة ولا إعادة تشغيل. فإن كان طلبًا شُحن أو كعكة بردت، فالمتابعة عليك يدويًا.

نداءات مطوّرك تعود مرفوضة

يقول طرفه إنه يتلقّى 422، وفي الجسم "error":"Invalid or missing webhook secret". وداخل Botragon تظهر الكلمات نفسها خطأً على سطر أحمر "Failed" في "Trigger History". ولا يصلك أي تنبيه — لا تجد هذا إلا إن نظرت.

لماذا: حوّلت "Security mode" إلى "Shared secret header"، ووصل نداؤه بلا سرّ، أو بسرّ قديم بعد "Regenerate"، أو بالسرّ الصحيح في ترويسة خاطئة لأن أحدهم عدّل حقل "Header name".

ما تفعله: تحقّق من ثلاثة أمور بالترتيب. أنه يرسل الترويسة X-Botragon-Webhook-Secret لا غيرها. وأن القيمة مطابقة — فإن لم يحفظها أحد لحظة ظهورها فلا سبيل إلى قراءتها: اضغط «إنشاء مفتاح جديد» في القسم 5 وأرسل القيمة الجديدة. وأن "Header name" لا يزال X-Botragon-Webhook-Secret؛ فإن غيّره أحد، فأعده، لأن Botragon لا يقرأ ذلك الحقل ولن ينقذك اسم آخر فيه.

أما إن عادت النداءات بـ 404 عارٍ وجسم فارغ، فالعنوان نفسه خطأ — مسار مكتوب خطأً، أو مسار عُدّل بعد أن نسخوه. ولا يُكتب شيء إطلاقًا في "Trigger History" حينها، لأن Botragon لم يعرف أصلًا أي ويب هوك يسجّل عليه. اضغط «نسخ الرابط» في القائمة، أو "Copy URL" في القسم 1، وأرسل لهم العنوان مرة أخرى.

وملاحظة تخصّ الشاشة العربية. إن لم تُفتح القائمة أصلًا، ظهر لك «تعذّر تحميل الويب هوك»، ومعه «تعذّر الوصول إلى الخادم. أعد المحاولة.» إن كان العطل في الاتصال، أو «خطأ غير متوقّع في الخادم. راجع السجلّات.» إن كان في الخادم. وعلى اللوحة العربية لا يُعرض إلا هذا النص وحده؛ أما اللوحة الإنجليزية فتعرض معه رسالة الخادم الخام. فإن كتبت إلى الدعم من لوحة عربية، فاعلم أنك ترى أقل مما يراه زميلك على اللوحة الإنجليزية، واذكر لهم رمز الخطأ إن ظهر لك.

---

→ العودة إلى دليل التاجر في Botragon