Webhooks

لا تمتلك تكاملًا أصليًا من Sorank مع نظام CMS الخاص بك؟ يتيح لك موصّل Webhook دفع المقالات التي تنتجها إلى أيّ URL، أو Zapier أو Make أو n8n أو نقطة نهاية مخصّصة على موقعك المبرمج الخاص، لكي تنشر محتواك أينما تريد.

كيف يعمل

عند نشر مقال في Sorank، نرسل طلب POST بحمولة JSON منظمة إلى الـ URL الذي قمت بإعداده. يمكن لنقطة النهاية أو أداة الأتمتة الخاصة بك معالجة الحمولة وإنشاء المنشور على مدوّنتك أو موقعك المخصّص أو أي أداة أخرى تقبل طلبات HTTP واردة.

⚠️ مهم: يرسل الـ webhook البيانات فقط، وأنت تنشرها

هذا أهمّ شيء يجب فهمه بشأن موصّل الـ Webhook. من جانبنا، تحزم Sorank كلّ ما تحتاجه داخل الـ JSON (العنوان، الـ slug، متن HTML كامل، وصف الميتا، الصور، اللغة والمزيد) وتطلقها إلى الـ URL الخاص بك. بمجرد إرسال الـ JSON بنجاح، تُعلم Sorank التسليم بأنه success.

حالة "success" هذه تؤكد شيئًا واحدًا فقط: البيانات غادرت Sorank وقبلتها نقطة النهاية الخاصة بك. لا توجد لدينا طريقة لمعرفة ماذا يحدث بعد ذلك في جانبك. لا يمكننا الكشف عمّا إذا كان رمزك قد قرأ الـ JSON فعلاً، أو ربط الحقول بشكل صحيح، أو دفع المقال ليظهر على موقعك.

بعبارة أخرى، الـ webhook هو مجرد آلية تسليم للبيانات. التقاطها وتحليلها ونشرها في CMS الخاص بك يقع بالكامل على عاتقك. إذا لم يظهر المقال في مدوّنتك رغم أن Sorank تعرض "success"، فإن المشكلة تكمن دائمًا تقريبًا في طريقة تقاطع تكاملك مع الحمولة ومعالجتها، وليس في التسليم نفسه.

الخطوة 1: فتح تكامل الـ Webhook

1. انقر على صورة ملفّك الشخصي في الزاوية العلوية اليمنى واختر Settings.
2. افتح علامة تبويب Integrations.
3. مرّر إلى بطاقة Webhook وانقر على Connect your website.

الخطوة 2: إعداد نقطة النهاية الخاصة بك

1. الصق الـ URL الوجهة في حقل Webhook URL (مثلاً catch hook لـ Zapier أو webhook لـ Make أو نقطة نهاية خادم خاص بك).
2. اختياريًا، أضف Secret token إذا كانت نقطة النهاية تتطلب مصادقة. سترفقه Sorank كرمز Bearer في ترويسة Authorization ليتحقق خادمك من أنّ الطلب قادم فعلاً من Sorank.
3. انقر على Test لإرسال حمولة عيّنة (نوع الحدث webhook.test) وتأكيد أن نقطة النهاية تردّ بشكل صحيح.
4. انقر على Save webhook لتفعيل التكامل.

تفاصيل طلب HTTP

كلّ webhook ترسله Sorank إلى نقطة النهاية الخاصة بك يتبع نفس عقد HTTP. إليك ما سيستقبله خادمك:

• Method: POST
• Content-Type: application/json
• User-Agent: SORANK-Webhook/1.0
• Authorization: Bearer {webhook_secret} (اختياريًا، يُرسل فقط إذا كنت قد أعددت سرًا في إعدادات تكاملك)

استخدم ترويسة User-Agent لتحديد حركة مرور Sorank في سجلّاتك، وتحقّق من ترويسة Authorization في جانبك للتأكد من أن الطلب قادم من Sorank وليس من متصل مجهول.

بنية حمولة الـ Webhook

تُصدر Sorank نوعين من أحداث الـ webhook. يتشاركان نفس المغلّف العلوي (event، delivery_id، timestamp، article) لذلك يحتاج تكاملك فقط إلى التبديل حسب حقل event لتوجيه الحمولة.

Event: article.published

يطلق في كل مرّة تنشر فيها مقالًا من Sorank. هذا هو الحدث الذي يجب أن تعالجه نقطة نهاية الإنتاج لديك لإنشاء المنشور في CMS الخاص بك أو لتشغيل تدفق الأتمتة لديك.

Event: webhook.test

يطلق عندما تنقر على زر Test في Sorank للتحقق من أن نقطة النهاية الخاصة بك يمكن الوصول إليها. تستخدم الحمولة قيمًا وهمية (id أصفار بالكامل، يحذف featured_image، images فارغ) لذلك يمكن لتكاملك تجاهلها بأمان أو استخدامها لتأكيد الاتّصال دون إنشاء منشور حقيقي.

مرجع الحقول

• event، نوع الحدث. إمّا article.published أو webhook.test. بدّل حسب هذا الحقل لتوجيه الحمولة.
• delivery_id، UUID فريد لكل محاولة تسليم. خزّنه في جانبك للحماية من التكرار عند إعادة المحاولة ومن النشر المزدوج.
• timestamp، طابع زمني ISO 8601 UTC لوقت إطلاق الحدث.
• article.id، معرّف فريد للمقال في Sorank.
• article.title، H1 / عنوان المقال.
• article.slug، slug ودود للـ URL، بأحرف صغيرة ومفصول بواصلات.
• article.meta_description، وصف ميتا SEO، جاهز للإسقاط في وسم <meta name="description"> الخاص بك.
• article.focus_keyphrase، عبارة مفتاحية رئيسية مستهدفة للمقال.
• article.content، متن المقال الكامل بصيغة HTML، بما في ذلك العناوين والفقرات والقوائم ووسوم الصور المدمجة.
• article.featured_image، كائن صورة الغلاف مع url، alt و placement. يتوفر فقط في أحداث article.published.
• article.images، مصفوفة من الصور الإضافية داخل المتن. كل مدخل يمتلك url، alt و placement. قد تكون فارغة.
• article.word_count، إجمالي عدد كلمات متن المقال.
• article.keyword، مطابق للعبارة المفتاحية الرئيسية، محفوظ كحقل منفصل للتوافق مع التكاملات القديمة.
• article.language، وسم لغة BCP 47 (مثل en-US، fr-FR).

حالات استخدام شائعة

• Zapier: استخدم محفّز "Catch Hook" لتوجيه المقالات إلى آلاف التطبيقات مثل WordPress أو Notion أو Airtable أو Google Sheets.
• Make: استخدم وحدة Webhooks لبناء أتمتة نشر مخصّصة متعددة الخطوات.
• n8n: اوصل عقدة Webhook في تدفّق ينشئ المنشور في CMS بدون رأس أو في مكتب الدعم الخلفي.
• Backend مخصّص: أرسل المقالات مباشرة إلى API خاص بك للنشر على موقع مبرمج يدويًا، أو CMS بدون رأس مثل Sanity أو Strapi، أو أي أداة داخلية.

نصائح

• انقر دائمًا على Test قبل الحفظ للتأكيد أن نقطة النهاية تقبل الطلب وترجع ردّ 2xx.
• بدّل حسب حقل event في جانب الخادم بحيث لا تنشئ طلبات webhook.test منشورات حقيقية أبدًا.
• استخدم delivery_id كمفتاح للثبات لتجنّب نشر المقال نفسه مرتين في إعادة المحاولات.
• احتفظ بـ Secret token خاصًا، وتحقّق من ترويسة Authorization على كل طلب، ودوّر السرّ بانتظام.
• استخدم نقطة نهاية HTTPS للحفاظ على أمان بيانات المقال أثناء النقل.
• بمجرد الاتصال، سيُرسل كلّ مقال ينشر في Sorank تلقائيًا إلى الـ URL الخاص بـ webhook لديك.

🔄 لماذا قد لا تظهر مقالاتك (أسباب الفشل)

لأن الـ webhook يوصل البيانات فقط، فإن "success" في Sorank لا يضمن أن المقال موجود مباشرة على موقعك. عندما يحدث خطأ ما، تكون المشكلة دائمًا تقريبًا في جانب المستقبل. إليك أكثر الأسباب شيوعًا وكيفية إصلاحها.

أسباب في جانب تكاملك

• مفتاح API خاص بـ CMS للقراءة فقط وليس للقراءة والكتابة، هذه واحدة من أكثر المشاكل شيوعًا. إذا كانت بيانات الاعتماد التي يستخدمها رمزك للكتابة في CMS الخاص بك (Sanity، Strapi، Contentful، أو أي backend بدون رأس) تمتلك فقط أذونات view / read، فإن نقطة النهاية ستستقبل الـ JSON لكنّها ستفشل بصمت في إنشاء المنشور. أنشئ مفتاحًا بصلاحية write وحدّثه في تكاملك.
• يستقبل رمزك الـ JSON لكنّه لا يدفعه أبدًا إلى CMS لديك، استقبال الحمولة هو نصف المهمّة فقط. تأكد أن نقطة النهاية تربط فعلاً حقول Sorank وتنشئ المنشور في CMS أو قاعدة البيانات. سجّل الحمولة الواردة وتأكد أن طلب النشر لديك يعمل وينجح.
• ربط الحقول غير صحيح، إذا توقّع رمزك أسماء حقول مختلفة عن تلك الموجودة في الحمولة، فقد يتم إنشاء المنشور فارغًا أو رفضه. تحقّق مجددًا من قراءة article.title، article.slug، article.content وغيرها، تمامًا كما هو موثّق أعلاه.
• نقطة النهاية ترجع 2xx لكنّها تُلقي خطأ بعد ذلك، إذا أقررت بالطلب قبل معالجته بشكل غير متزامن، فإن أي فشل لاحق في منطق النشر لن يكون مرئيًا لـ Sorank. تحقّق من سجلّات خادمك الخاص لالتقاط هذه.

أسباب في جانب التسليم

• نقطة نهاية الـ webhook لديك لم تعد تردّ (الخادم غير متّصل)، أعد خادمك إلى العمل وتحقّق من أن الـ URL يردّ بشكل طبيعي.
• تغيّر الـ URL لـ webhook ولكنّه لم يُحدّث في Sorank، حدّث الـ URL في إعدادات تكامل Sorank لديك.
• أعدت إنشاء سرّ الـ webhook في جانبك، حدّث السرّ في Sorank حتّى يتطابق مع ذلك الذي يتوقّعه خادمك الآن في ترويسة Authorization.
• نقطة النهاية ترجع خطأ لا تستطيع Sorank تفسيره، تحقّق من سجلّات خادمك لتحديد المشكلة، ثم أصلحها في جانب الـ webhook لديك.
• جدار حماية في خادمك يحجب طلباتنا، أضف عناوين IP لـ Sorank إلى القائمة البيضاء في جدار حمايتك، أو اسمح لـ User-Agent SORANK-Webhook/1.0.
• نقطة نهايتك تأخذ أكثر من 30 ثانية للردّ، حسّن نقطة نهايتك لتردّ بشكل أسرع، أو أقرر بالطلب فورًا وعالجه بشكل غير متزامن.

عندما لا تستطيع Sorank تسليم مقال إلى نقطة النهاية الخاصة بك، يتم إيقاف جدولة المحتوى الخاصة بك تلقائيًا وستتلقّى بريدًا إلكترونيًا. بمجرد أن تصلح المشكلة وتعيد الاتّصال بـ webhook في Sorank، تستأنف الجدولة تلقائيًا. مقالك تم إنشاؤه بالفعل ومخزّن بأمان، لا شيء يفقد.

🚀 لست مطوّرًا؟ استضف مدوّنتك على Sorank بدلاً من ذلك

يتطلّب الـ webhook منك كتابة وصيانة رمز يلتقط الـ JSON وينشره على موقعك. إذا أنشأت موقعك بأداة no-code أو AI، مثل Lovable أو Base44 أو Cursor أو Claude Code، ولم تتمكّن من تطوير واستضافة نقطة نهاية تلتقط الـ webhook وتنشر المقال، فهناك طريق أبسط بكثير.

أنشأنا حلاً حيث يمكنك استضافة مدوّنتك تلقائيًا على النطاق الفرعي الخاص بك، مباشرة على Sorank. بدون رمز، بدون نقطة نهاية للصيانة، بدون webhook للالتقاط. تعرّف على كيفية عمله هنا: Host your blog on Sorank.

تبحث عن تكامل أصلي بدلاً من ذلك؟

إذا كانت منصّتك مدعومة، فإن الموصّل المباشر أسهل من الـ webhook. اطّلع على أدلّتنا لـ Webflow، Shopify، WordPress.org، WordPress.com، Wix و HubSpot.

المشكلة مستمرّة بعد التحقّق؟

إذا تحقّقت من النقاط أعلاه وما زال النشر يفشل، فردّ مباشرة على البريد الإلكتروني الذي تلقّيته: سيتفحّص فريقنا ما يحدث في حسابك.

تبقى مقالاتك مولّدة ومخزّنة بأمان في Sorank. بمجرد إعادة الاتّصال، تستأنف جدولة المحتوى تلقائيًا من حيث توقّفت.