خطافات الويب (webhook) لوسائل التواصل الاجتماعي: التعليقات والإشارات والرسائل إلى نقطة النهاية (endpoint) واحدة
تُمرّر easyCoexistence أحداث وسائل التواصل إلى endpoint الخاص بك عبر HTTPS فور وقوعها: التعليقات والإشارات والرسائل المباشرة من Instagram و Facebook، والتعليقات من TikTok. يصل كل حدث في مظروف واحد، ويبقى حدث الشبكة داخله دون تغيير، ويُوقَّع لكل حساب بالترويسة X-EC-Signature. فعّل ذلك لكل حساب عبر set_social_webhook_destination من Claude أو ChatGPT، أو عبر Partner API. وتصل رسائل رقم WhatsApp إلى خادمك أيضًا.
- التعليقات والإشارات والرسائل المباشرة فور حدوثها
- مظروف واحد، موقّع لكل حساب
- يُضبط من Claude أو ChatGPT أو Partner API
لن تُفرض أي رسوم لمدة 3 أيام. ألغِ في أي وقت.
عدد مرات إرسال easyCoexistence لكل حدث وسائل تواصل مُعاد توجيهه؛ فهي لا تحتفظ بنسخة، ولذلك لا يُعاد إرساله لاحقًا.
المدة التي يستغرقها إشعار comment.update من TikTok للإبلاغ عن تعليق أُنشئ أو حُذف أو تغيّرت رؤيته على مقاطع الفيديو العامة لحساب تملكه.
المكان الذي تتلقى فيه تطبيقات Instagram Login إشارات @mentions: داخل إشعار webhook التعليقات، لا كحقل مستقل.
ما تُبلغ عنه إشعارات YouTube الفورية لقناة ما: رفع فيديو جديد، أو عنوان جديد، أو وصف جديد.
المدة التي تستمر فيها Meta في إعادة محاولة webhook واتساب لم يقبله خادمك، وهو ما قد يؤدي إلى تسليم نسخ مكررة.
أي أحداث ترسلها كل شبكة؟
ترسل Instagram و Facebook و TikTok الأحداث إلى easyCoexistence، فتمررها إلى عنوان URL الذي تحدده لذلك الحساب. ترسل Instagram التعليقات الجديدة، وتصل الإشارات @mentions داخل إشعار التعليقات، إضافةً إلى الرسائل المباشرة. وترسل صفحة Facebook نشاط الخلاصة، الذي يشمل التعليقات الجديدة، إضافةً إلى رسائل Messenger وإشارات الصفحة. وترسل TikTok الحدث comment.update، الذي يُطلق عند إنشاء تعليق أو حذفه أو تغيّر رؤيته.
لا ترسل YouTube وLinkedIn إلى easyCoexistence أي أحداث تعليقات أو رسائل، لذلك يقرأ الوكيل تعليقاتهما عند الطلب. أما رسائل رقم WhatsApp فتسير في مسار خاص: تُسلّمها Meta مباشرة إلى خادمك في الوضع المباشر، أو تمررها easyCoexistence موقّعة عندما يعمل الرقم في الوضع المُدار.
| What arrives | Sent by | |
|---|---|---|
| Comments, mentions and DMs | easyCoexistence, signed per account | |
| Feed activity, Messenger and mentions | easyCoexistence, signed per account | |
| TikTok | comment.update events | easyCoexistence, signed per account |
| Messages and echoes from the app | Meta directly, or easyCoexistence in managed mode | |
| YouTube | No comment events | Read with list_youtube_comments |
| No comment events | Read with list_linkedin_comments |
كيف يبدو الحدث المُعاد توجيهه؟
المظروف نفسه بصيغة JSON على كل شبكة، يُرسل مع Content-Type application/json: platform، أي الشبكة؛ و account_id، وهو المعرّف الذي تستخدمه أدوات MCP وPartner API؛ و external_id، أي معرّف الحساب على الشبكة؛ و entry، أي حدث الشبكة الأصلي كما وصل. في Instagram وFacebook يكون entry هو مدخل webhook من Meta، مع changes للتعليقات والإشارات وmessaging للرسائل المباشرة. أما في TikTok فيحتوي على حدث comment.update، مع comment_id وvideo_id وparent_comment_id كنصوص، حتى لا تُقرَّب المعرّفات ذات 64 بت. تصل رسالة Messenger هكذا:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400512,
"messaging": [
{
"sender": { "id": "<PAGE_SCOPED_ID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399870,
"message": { "mid": "<MESSAGE_ID>", "text": "Are you open on Sunday?" }
}
]
}
}كيف تتحقق من X-EC-Signature؟
بالسر الموقّع الذي يُعاد عند تحديد الوجهة، وهو فريد لذلك الحساب ويُعرض مرة واحدة. تكون الترويسة بالشكل t=<unix>,v1=<hex>، وv1 هو HMAC-SHA256 للطابع الزمني، متبوعًا بنقطة ثم نص الطلب الخام، ويُحسب بالسر نفسه كمفتاح. اقرأ نص الطلب كبايتات قبل تحليله، وارفض الطابع الزمني الذي يبعد أكثر من 5 دقائق عن ساعتك، وابحث عن السر بالحقل account_id في الحدث، ثم قارن الملخصين بمقارنة ثابتة الزمن. بعد ذلك أجب بـ 2xx وضع العمل في قائمة انتظار. في PHP يتطلب ذلك بضعة أسطر:
<?php
// POST /hooks/social: one endpoint for the events of each account
$raw = file_get_contents('php://input'); // the exact bytes that were signed
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_EC_SIGNATURE'] ?? ''), $sig);
$event = json_decode($raw, true); // platform, account_id, external_id, entry
$secret = secret_for($event['account_id'] ?? ''); // the signing_secret stored for that account
$fresh = ctype_digit($sig['t'] ?? '') && abs(time() - (int) $sig['t']) <= 300;
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, (string) $secret);
if (!$secret || !$fresh || !hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(401);
exit;
}
http_response_code(204);
enqueue($event); // keep this quick: the forward waits 8 seconds and is never resentكيف تُفعّل التوجيه لحساب؟
من مساعد ذكي أو من خادمك الخلفي. اطلب من Claude أو ChatGPT تشغيل set_social_webhook_destination مع الحساب وعنوان URL الخاص بك عبر HTTPS، أو استدعِ PUT /api/v1/channels/:id/webhook في Partner API بمفتاحك ec_live_ وجسم يحتوي على url. يعيد الأمران signing_secret للحساب مرة واحدة، فاحفظه مرتبطًا بـ account_id حينها. استدعاء أي منهما مرة أخرى يصدر سرًا جديدًا، والقيمة null في url توقف التوجيه.
يجب أن يكون عنوان URL بصيغة HTTPS على مضيف عام: يُرفض العنوان الخاص عند تحديده وعند التسليم. يمكن لـ endpoint واحد خدمة حسابات كثيرة، لأن كل حدث يذكر account_id الخاص به. أما لرقم WhatsApp فتوجّه set_webhook_destination تسليمات Meta إليك، بينما تُرسلها set_inbound_mode مع forward_url موقّعة بدلًا من ذلك.
ماذا يحدث عندما يكون endpoint بطيئًا أو متوقفًا؟
لا يُعاد إرسال الحدث. تجري easyCoexistence محاولة واحدة، وتنتظر ردًا لمدة تصل إلى 8 ثوانٍ، ولا تتبع أي عمليات توجيه، ولا تحتفظ بنسخة، لأن إعادة المحاولة تعني تخزين تعليقات عملائك ورسائلهم. أجب بـ 2xx فور التحقق من التوقيع، ونفّذ العمل البطيء من قائمة انتظار، وأزِل التكرار بالمعرّفات الخاصة بالشبكة نفسها، كمعرّف التعليق أو الرسالة mid، تحسبًا لوصول الحدث مرتين.
يختلف WhatsApp. في الوضع المباشر، تعيد Meta محاولة التسليم الذي لم يقبله خادمك لمدة تصل إلى 7 أيام. وفي الوضع المُدار، تضع easyCoexistence الرسائل في قائمة انتظار لـ forward URL الخاص بك وتعيد المحاولة بتراجع متدرج. وتُعاد محاولة أحداث حالة الشريك، مثل انقطاع اتصال، لمدة 33 ساعة تقريبًا.
كيف تصل تعليقات YouTube وLinkedIn إلى الوكيل؟
بقراءتها وفق جدول زمني. لا ترسل إشعارات YouTube الفورية تعليقات، بل تُبلغ عن رفع فيديو جديد أو عنوان جديد أو وصف جديد. ولا تستقبل easyCoexistence أي أحداث تعليقات من LinkedIn، لذلك لا تمرّر أي منهما شيئًا. بدلًا من ذلك يتحقق الوكيل بنفسه: تعيد list_youtube_comments سلاسل تعليقات فيديو معيّن أو القناة كلها، بما فيها التعليقات التي تنتظر المراجعة، وتعيد list_linkedin_comments تعليقات منشور أو الردود تحت تعليق بعينه. في n8n أو Make أو Zapier يبدأ مشغّل الجدول الزمني الفحص؛ وفي كودك الخاص، تستدعي مهمة cron بيانات اعتماد القناة وتطلب مباشرة commentThreads من YouTube أو endpoint comments في LinkedIn.
كيفية إعداده
- Set the destinationRun set_social_webhook_destination with the account and an HTTPS URL, or call PUT /api/v1/channels/:id/webhook with your ec_live_ key.
- Store the secretSave the signing_secret from the response against that account_id, since it is shown only once.
- Verify each deliveryCheck that the timestamp is fresh and that v1 matches an HMAC-SHA256 of the timestamp, a dot and the raw body.
- Acknowledge, then workAnswer 2xx straight away and hand the event to a queue, because easyCoexistence sends it only once.
الأخطاء الشائعة
- التحقق من HMAC على JSON بعد تحليله. يغطي التوقيع النص الخام بايتًا ببايت، وإعادة تسلسل الكائن المحلَّل تغيّر تلك البايتات، فتحقق قبل التحليل.
- استخدام سر واحد لكل الحسابات. يوقّع كل حساب بسره الخاص، لذا ابحث عنه بالحقل account_id للحدث قبل مقارنة v1.
- إعادة تحديد الوجهة دون تحديث endpoint الخاص بك. كل استدعاء يصدر سرًا جديدًا، ويتوقف السر القديم عن التوقيع فورًا، فاحفظ الجديد في الحال.
- تقديم عنوان URL يعيد التوجيه. لا تتبع easyCoexistence عمليات التوجيه، فالانتقال إلى مسار أو مضيف جديد يُضيّع الحدث؛ لذا عيّن العنوان النهائي.
ترسل easyCoexistence تعليقات Instagram و Facebook وإشاراتهما ورسائلهما المباشرة، وتعليقات TikTok، إلى endpoint الخاص بك فور حدوثها، موقّعة لكل حساب، وتوجّه رسائل WhatsApp إلى خادمك، فيتلقى وكلاؤك الذكيون رسائل العملاء عبر الواجهات الرسمية لكل شبكة، مع مراقبة كل اتصال على مدار الساعة. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
كيف تصل رسائل رقم WhatsApp إلى endpoint الخاص بي؟
بإحدى طريقتين. تُسلّم set_webhook_destination الرسائل إلى خادمك مباشرة، بينما تجعل set_inbound_mode مع forward_url تمررها easyCoexistence موقّعة بالترويسة X-EC-Signature، مع إعادة المحاولة بتراجع متدرج.
هل يمكن أن يصل الحدث نفسه مرتين؟
يمكن ذلك، لذا أزِل التكرار بالمعرّفات الخاصة بالشبكة نفسها، كمعرّف التعليق أو الرسالة mid. وقد تجلب محاولات Meta المتكررة لتسليم رسالة WhatsApp لم يقبلها خادمك، لمدة تصل إلى 7 أيام، نسخًا مكررة أيضًا.
هل يمكن لـ endpoint واحد تلقي أحداث من عدة حسابات؟
نعم. يحمل كل حدث platform وaccount_id، فيمكن لعنوان URL واحد خدمة حسابات كثيرة، شريطة أن يتحقق من كل توقيع بالسر الخاص بذلك الحساب.
كم تكلّف easyCoexistence لـ webhooks وسائل التواصل الاجتماعي؟
من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ويقل السعر كلما أضفت اتصالات، والسعر واحد على كل شبكة. يشمل ذلك التوجيه وخادم MCP وPartner API، مع فترة تجريبية مجانية مدتها 3 أيام.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في