إعادة محاولات webhook في WhatsApp والتكرار والترتيب: كيفية التعامل معها
يعيد Meta محاولة إرسال خطاف الويب (webhook) الخاص بـ WhatsApp عند استلام أي استجابة غير HTTP 200، فورًا ثم بوتيرة متناقصة لمدة تصل إلى 7 أيام، ثم يُسقطه بعد ذلك. تُرسل المحاولات إلى كل تطبيق مشترك في الحساب، لذا التكرار أمر طبيعي. أجب بالرمز 200 بسرعة، وأزل التكرار اعتمادًا على معرّف الرسالة، أو على معرّف الحالة مع الحقل status، ورتّب الأحداث حسب الطوابع الزمنية الخاصة بها.
يربط easyCoexistence رقم تطبيق WhatsApp Business الخاص بك بواجهة Cloud API لدى Meta عبر Coexistence، ويستوعب إعادات الإرسال من Meta قبل أن تراها أتمتتك، فلا تحصل رسالة معادة على رد ذكاء اصطناعي ثانٍ.
المدة التي يواصل Meta خلالها إعادة محاولة webhook لم يتلقَّ HTTP 200، قبل إسقاطه.
يجمع Meta معظم التحديثات في طلب POST واحد، لكنه لا يضمن التجميع، لذا عالج كل طلب على حدة.
أكبر حمولة يمكن أن يحملها طلب POST الخاص بـ webhook في WhatsApp.
المدة التي يتذكر فيها easyCoexistence معرّف كل رسالة واردة، حتى لا تُشغَّل الأتمتة مرتين عند إعادة تسليم الرسالة.
عدد المحاولات لكل إعادة توجيه إلى عنوان Forward URL الخاص بك، ينتظر كل منها 10 ثوانٍ للحصول على استجابة 2xx، على مدى نحو 33 ساعة.
متى يعيد Meta محاولة webhook في WhatsApp؟
كلما حصل التسليم إلى نقطة النهاية (endpoint) لديك على استجابة HTTP غير 200، أو تعذّر تسليمه أصلًا. يعيد Meta المحاولة فورًا، ثم عدة مرات أخرى بوتيرة متناقصة خلال الأيام السبعة التالية، ثم يُسقط ما لم يُقرّ باستلامه بعد ذلك. تُرسل المحاولات إلى كل تطبيق مشترك في حساب WhatsApp Business لذلك الحقل، ولهذا يحذّر Meta من أنها قد تُنتج إشعارات مكررة. لا توجد واجهة برمجة تطبيقات (API) لاسترجاع webhooks السابقة، لذا فالتسليم الذي تنتهي مهلته السبعة أيام يضيع على نظامك.
لماذا تصل التكرارات حتى عندما يكون خادمك سليمًا؟
لأن التسليم قد ينجح من جهتك ومع ذلك يبدو فاشلًا بالنسبة إلى Meta. فالمعالج الذي ينجز عمله قبل الرد قد يتجاوز مهلة انتظار Meta، فيعيد Meta إرسال شيء سبق أن عالجته. وتُحسب كإخفاقات إعادة تشغيل الخادم في منتصف الطلب بسبب النشر، أو قيام موازن الأحمال (load balancer) بإرجاع الرمز 502 لحظةً، أو إرجاع 201 أو 204 بدلًا من 200. وتضيف الدفعات حالة إضافية: قد يحمل طلب POST واحد تحديثات كثيرة، فتسبب مهلة على دفعة كبيرة عودة الدفعة كلها، بما فيها التحديثات التي عالجتها.
بأي مفتاح تُزيل التكرار؟
بمعرّفات Meta نفسها، وتُحدَّد لكل نوع حدث، لأن الرسالة الواحدة تُنتج عدة webhooks بشكل مشروع. فمفتاح الحالة دون قيمة status سيُسقط delivered ويعتبرها نسخًا من sent، ومفتاح المكالمة دون نوع الحدث سيُبقي المرحلة الأولى فقط من المكالمة. خزّن المفاتيح مع فهرس فريد (unique index)، حتى لا يتمكن عاملان يعالجان المحاولة نفسها من الفوز معًا:
بأي ترتيب تصل webhooks؟
ليس بالضرورة بالترتيب الذي وقعت به الأحداث. لا يقدّم توثيق Meta أي ضمان للترتيب، والتسليم المعاد يصل بعد أحداث أحدث، وقد تتخطى الحالة خطوة: يرسل Meta read دون delivered عندما تُقرأ الرسالة لحظة وصولها. لذلك خزّن الأحداث مع حقل الطابع الزمني الخاص بها، وقارن الحالة برتبتها لا بوقت وصولها، ودع رسالة العميل الأحدث تتغلب على رسالة أقدم وصلت متأخرة. وفي الأرقام المتصلة عبر Coexistence قد يتداخل استيراد السجل لمرة واحدة مع الرسائل المباشرة حول الإعداد الأولي، ومعرّف الرسالة هو ما يوفّق بين الاثنين.
كيف يبدو المعالج الآمن؟
أربع خطوات: تحقّق، ثم أجب بالرمز 200 تمامًا، ثم أزل التكرار، ثم اعمل من قائمة انتظار، حتى لا يقع أي شيء بطيء بين طلب Meta ورَدّك. تتحقق هذه النسخة من X-Hub-Signature-256 باستخدام سر التطبيق الخاص بتطبيق Meta الخاص بك. أما الرقم المتصل عبر easyCoexistence فيوقّع Meta بسر تطبيق easyCoexistence، لذلك تُصادَق الوجهة المباشرة بسر طويل ضمن مسار عنوان URL، أو تنتقل إلى إعادة التوجيه المُدارة الموقّعة لكل رقم.
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);كيف يتعامل easyCoexistence مع المحاولات على رقم متصل؟
عند الدخول، يتحقق easyCoexistence من توقيع Meta، ويجيب بالرمز 200، ويشغّل الأتمتة بعد الرد، فلا يعيد Meta المحاولة لأن رد الذكاء الاصطناعي استغرق بضع ثوانٍ. يُحتفظ بكل معرّف رسالة وارد لمدة 7 أيام، وهي طول نافذة إعادة المحاولة لدى Meta، فتُتعرَّف الرسالة المعادة ولا تُشغّل ردًا آليًا ثانيًا.
عند الخروج إلى عنوان Forward URL الخاص بك، يصبح كل تغيير من Meta تسليمًا واحدًا بمعرّف في X-EC-Delivery يبقى ثابتًا عبر إعادات التوجيه: 7 محاولات على مدى نحو 33 ساعة، ينتظر كل منها 10 ثوانٍ للحصول على استجابة 2xx. والتغيير الذي يعيد Meta نفسه إرساله يُعاد توجيهه تحت معرّف تسليم جديد، لذا أزل التكرار اعتمادًا على معرّفات Meta داخل value أيضًا.
الأخطاء الشائعة
- إزالة التكرار في الحالات بالمعرّف وحده. فـ sent وdelivered وread تشترك في wamid، لذا يحتاج المفتاح إلى الحالة أيضًا.
- المعالجة قبل الرد. المعالج البطيء يجعل Meta يعيد عملًا أنجزته سابقًا، لذا أجب بالرمز 200 أولًا، واعمل من قائمة انتظار.
- إرجاع 201 أو 204. يعامل توثيق Meta أي حالة غير 200 كتسليم فاشل ويعيد محاولته.
- إزالة تكرار إعادات التوجيه بـ X-EC-Delivery وحده. يصل التغيير الذي يعيد Meta إرساله تحت معرّف تسليم جديد، لذا أبقِ معرّفات Meta مفتاحًا ثانيًا.
تُرسل عمليات إعادة التوجيه إلى خادمك موقّعة ومرتّبة في قائمة انتظار ومعاد محاولتها، ويُراقَب كل رقم على مدار الساعة طوال أيام الأسبوع. من US$ 9 إلى US$ 0.75 لكل رقم شهريًا، وينخفض السعر كلما أضفت أرقامًا، مع فترة تجريبية مجانية لأول 3 أيام.
الأسئلة الشائعة
كم من الوقت يجب أن أحتفظ بالمعرّفات التي رأيتها؟
7 أيام على الأقل، وهي نافذة إعادة المحاولة لدى Meta. فالتسليم الذي يعيد Meta محاولته في اليوم السادس يجب أن يطابق مفتاحه، وإلا سيُعالج كجديد.
ماذا يحدث لرسائل عملائي إذا تعطلت نقطة النهاية لدي لأيام؟
يعيد Meta المحاولة لمدة تصل إلى 7 أيام، ثم يُسقط webhooks. وفي الأرقام المتصلة عبر Coexistence تبقى المحادثات في تطبيق WhatsApp Business على الهاتف، فيستطيع النشاط التجاري الرد منه.
هل يمكنني إعادة تشغيل webhooks فاتتني؟
ليس من Meta: لا توجد API لبيانات webhooks التاريخية. أما استيراد السجل لمرة واحدة في الأرقام المتصلة عبر Coexistence فيعمل عند الإعداد الأولي فقط، ولا يمكن طلبه مرة أخرى لنفس الاتصال.
هل يرسل Meta التحديث نفسه إلى أكثر من خادم؟
يرسله إلى كل تطبيق مشترك في حساب WhatsApp Business لذلك الحقل. ومع تجاوز الوجهة (destination override)، تُرسل حقول رسائل الرقم إلى عنوان التجاوز بدلًا من رد الاستدعاء الافتراضي لذلك التطبيق.
تابع القراءة
هل أنت مستعد للبدء؟
أعد إعداد WhatsApp Coexistence خلال دقائق، وليس أشهر. يواصل التطبيق العمل على الهاتف.
ابدأ الفترة التجريبية المجانيةتم التحقق في