الـ idempotency في webhooks: المفاتيح وإعادة المحاولة والآثار الجانبية
باختصار: يعيد معظم المرسلين المحاولة عند انتهاء المهلة وردود 5xx وانقطاع الشبكة، ويترك الباقون إعادة الإرسال لكم. نعامل كل تسليم على أنه مرة واحدة على الأقل ونجعل المعالجة idempotent (أي أن تكرار الطلب لا يغيّر النتيجة): لكل حدث مفتاح ثابت، وتُحفظ حالة المعالجة قبل أي أثر جانبي، ويُحتفظ بالمفاتيح طوال أطول مدة لإعادة المحاولة لدى المرسل. المفتاح المكتمل يحصل على 2xx.
1.0 المرسل يعيد المحاولة، والمستقبِل يفترض التسليم مرة واحدة على الأقل
قد يكون الـ webhook الذي انتهت مهلته عندكم قد طُبِّق بالفعل. المرسل لا يعرف ذلك، فيعيد المحاولة. والأمر نفسه يحدث مع ردود 500 ومع أعطال الشبكة العادية. حين يُبنى النظام على أن كل حدث يصل مرة واحدة بالضبط، تظهر رسائل بريد مكررة، وحركات مخزون مزدوجة، أو مستندان في ERP لدفعة واحدة.
تختلف المدة التي يواصل فيها المزوّدون المحاولة. Stripe مثلًا يعيد محاولة تسليم webhooks في الوضع الحي مدة تصل إلى ثلاثة أيام مع تراجع أُسّي (exponential backoff). أما GitHub فلا يعيد إرسال التسليمات الفاشلة تلقائيًا؛ ويمكنكم إعادة إرسال أي تسليم من آخر ثلاثة أيام من الواجهة أو عبر API. اقرؤوا ما يوثّقه المزوّد عن إعادة المحاولة وإعادة الإرسال، وحدّدوا مدة الاحتفاظ لإزالة التكرار وفق أطول نافذة تهمّكم. أما افتراض أننا “نرد بسرعة فلن تكون هناك إعادة محاولة” فلا يُعتمد عليه.
2.0 اختيار مفتاح ثابت
| المصدر | المفتاح المعتاد | ملاحظات |
|---|---|---|
| معرّف الحدث لدى المزوّد | evt_…، GUID التسليم | الخيار الأول إذا كان فريدًا لكل حدث منطقي |
| مفتاح مركّب | (provider, event_id) | حين يستقبل نظام واحد webhooks من عدة مزوّدين |
| ترويسة | Idempotency-Key، X-GitHub-Delivery | Idempotency-Key لواجهات API الصادرة الخاصة بكم. ويُبقي GitHub قيمة X-GitHub-Delivery نفسها عند إعادة الإرسال، فهي تميّز الحدث لا المحاولة |
| كائن الأعمال | (event_type, object_id) | ضروري إذا كان المزوّد قد يصدر كائنَي Event للتغيير نفسه |
خزّنوا المفتاح مع قيد تفرّد (unique constraint) أو بكتابة شرطية ذرّية. الحالة الصعبة هي التزامن: قد يرى عاملان (workers) معًا أن المفتاح “غير موجود” ما لم تكن عملية الإدراج نفسها هي البوابة.
3.0 تتبّع الحالة لا مجرد علَم «تم»
| الحالة | المعنى | عند تسليم جديد للمفتاح نفسه |
|---|---|---|
| processing | قُبل والعمل جارٍ (مع lease أو مالك اختياريًا) | الانتظار، أو إرجاع تعارض، أو الالتحاق بالمحاولة الجارية؛ لا يُبدأ مسار ثانٍ للآثار الجانبية |
| completed | حُفظ واكتملت الآثار الجانبية | إرجاع 2xx فورًا؛ دون آثار جانبية |
| failed_retryable | فشل مؤقت؛ إعادة المحاولة آمنة | إعادة المحاولة مع التراجع، بالمفتاح نفسه |
| failed_terminal | لن ينجح دون تدخل شخص | تنبيه؛ لا تُترك الحلقة التلقائية تدور بلا نهاية |
تُسجَّل حالة processing في الكتابة الدائمة نفسها التي تقبل المفتاح أول مرة، قبل أي بريد أو خصم أو استدعاء لـ ERP. ولا تُسجَّل completed إلا بعد أن يصبح لتلك الآثار الجانبية سجل دائم خاص بها (أو بعد تثبيت صف الـ outbox الذي سيشغّلها).
4.0 نافذة إعادة المحاولة مقابل مدة الاحتفاظ
هناك مدّتان يجب أن تتوافقا:
- نافذة إعادة المحاولة لدى المرسل: المدة التي قد يرسل فيها المزوّد (أو سكربت إعادة الإرسال لديكم) الحدث نفسه مجددًا.
- مدة الاحتفاظ لإزالة التكرار لدى المستقبِل: المدة التي تُحفظ فيها المفاتيح والنتائج ليُتعرَّف على التكرار المتأخر.
يجب أن تكون مدة الاحتفاظ لا تقلّ عن نافذة إعادة المحاولة التي تقبلونها. إذا انتهت صلاحية المفاتيح قبلها، تبدو إعادة المحاولة المتأخرة حدثًا جديدًا. إعادة الإرسال اليدوي تصل عادةً إلى أبعد من ذلك: يعيد Stripe المحاولة تلقائيًا حتى ثلاثة أيام، لكن لوحة التحكم تتيح إعادة إرسال الحدث خلال 15 يومًا، وأداة CLI خلال 30 يومًا. فإذا كان فريق التشغيل يعيد الإرسال من لوحة التحكم بعد انتهاء مدة الاحتفاظ، فإما أن تُمدَّد مدة الاحتفاظ، وإما أن يُشترط مفتاح جديد مع مسار مطابقة صريح.
5.0 الحفظ قبل الإقرار
الحالة المزعجة: أنهى المعالج العمل، ثم انقطع الاتصال قبل أن يرى المرسل 2xx. يعيد المرسل المحاولة. إن لم يُحفظ النجاح إلا في الذاكرة، تُنفَّذ الآثار الجانبية مرتين.
بهذا الترتيب نكتب:
- اكتبوا الحدث (أو صف outbox) وحالة processing / completed أولًا.
- لا تُرجعوا 2xx إلا بعد تثبيت هذه الكتابة.
- شغّلوا الآثار الجانبية غير الـ idempotent من السجل الدائم، بعد بوابة إزالة التكرار.
- إذا كانت الآثار الجانبية بطيئة، فأقرّوا بالاستلام بعد القبول الدائم وأكملوها بشكل غير متزامن، مع بقاء المفتاح نفسه وآلة الحالات نفسها.
6.0 الآثار الجانبية خلف البوابة
كل ما يصعب التراجع عنه، مثل إرسال بريد أو خصم من بطاقة أو دفع مستند إلى ERP أو فتح تذكرة، لا يُنفَّذ إلا بعد حجز المفتاح. تكرارات المفتاح completed تتخطى هذا المسار وتُرجع نجاحًا. وإن لم يكن الأثر الجانبي نفسه idempotent في الطرف الآخر، فأعطوه مفتاح أعمال خاصًا به (رقم الطلب، رقم الفاتورة) حتى لا يُنشئ الإرسال الثاني مستندًا ثانيًا.
7.0 الترتيب مع التسليم مرة واحدة على الأقل
كثيرًا ما لا يضمن المزوّدون الترتيب. قد يصل حدث updated قبل created، وقد تأتي إعادة محاولة لحمولة أقدم بعد حمولة أحدث. الـ idempotency وحدها لا تعالج ذلك. احتفظوا برقم إصدار أو تسلسل أو updated_at لكل كائن أعمال وتجاهلوا الكتابات القديمة، أو اجلبوا المورد الحالي من المزوّد قبل تغيير الحالة المحلية.
8.0 ما يُسجَّل وما يُنبَّه عليه
- فهرسة مخزن إزالة التكرار بالمفتاح، حتى يكون سؤال “هل عالجنا
evt_…من قبل؟” استعلامًا واحدًا. - تسجيل كل محاولة: المفتاح، والنتيجة (مكرر / قيد المعالجة / مكتمل / فاشل)، وزمن الاستجابة، ورقم المحاولة.
- بيانات الدفع والبيانات الشخصية لا تدخل السجلات المشتركة؛ نسجّل بصمة (digest) ومعرّفنا الداخلي فقط.
- التنبيه على المفاتيح العالقة في processing بعد انتهاء الـ lease، وعلى القفزات المفاجئة في التكرارات (وهي غالبًا موجة إعادة محاولات من المرسل بعد انقطاع).
إذا كنتم تبنون مستقبِلات webhook للمدفوعات أو ERP أو سحابات الأجهزة، فراجعوا الويب والسحابة وإدارة الأجهزة، أو حدثونا عن مشروعكم.
المراجع
- Stripe، Receive Stripe events in your webhook endpoint: https://docs.stripe.com/webhooks
- Stripe، Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- GitHub، Best practices for using webhooks: https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
- GitHub، Redelivering webhooks: https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks
- IETF HTTPAPI WG، The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-07 (مسودة إنترنت منتهية الصلاحية): https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
الأسئلة الشائعة
يقول المزوّد إنه يرسل كل حدث مرة واحدة. هل ما زلنا بحاجة إلى مخزن لإزالة التكرار؟
العقد الشائع في الواقع هو التسليم مرة واحدة على الأقل: انتهاء المهلة وردود 5xx وانقطاعات الشبكة القصيرة كلها تؤدي إلى إعادة المحاولة. مفتاح ثابت مع مدة احتفاظ تغطي أطول مدة لإعادة المحاولة لدى المزوّد هو ما يمنع تكرار الآثار الجانبية حين تصل الحمولة نفسها مرة أخرى.
ماذا نُرجع إذا وصل طلب مكرر والمحاولة الأولى ما زالت قيد المعالجة؟
نُرجع تعارضًا أو إشارة انتظار قصيرة بحسب ما يوثّقه المرسل، ولا نبدأ أبدًا مسارًا ثانيًا للآثار الجانبية للمفتاح نفسه. نُبقي الصف في حالة processing مع lease (مالك ومدة انتهاء)، ولا نضع عليه وسم completed إلا بعد انتهاء الحفظ والآثار الجانبية.
كم من الوقت نحتفظ بالمفاتيح التي عولجت؟
على الأقل طوال نافذة إعادة المحاولة التلقائية لدى المرسل، ويُفضَّل حتى نهاية فترة إعادة الإرسال اليدوي التي ينشرها. إذا انتهت صلاحية المفتاح ثم وصل الحدث نفسه، فسيعامله المستقبِل حدثًا جديدًا وقد يكرر عملًا غير idempotent.
أرجعنا 200، لكن البريد أو الإرسال إلى ERP لم يُنفَّذ. كيف نستدرك ذلك؟
احفظوا الحدث وحالة معالجته قبل إرجاع 2xx، ثم شغّلوا الآثار الجانبية انطلاقًا من هذا السجل الدائم أو من outbox. إرجاع النجاح قبل تثبيت الكتابة يعني أن أي عطل محلي بعده لا يترك سجلًا يمكن الاستئناف منه، بينما يعدّ المرسل الحدث قد سُلِّم.
تصل الأحداث أحيانًا بغير ترتيبها. هل يحل مفتاح idempotency هذه المشكلة؟
المفتاح يمنع فقط تطبيق الحدث نفسه مرتين. الترتيب يحتاج إلى قواعد مستقلة: تجاهل النسخ القديمة بالاعتماد على رقم تسلسلي أو على updated_at، أو جلب الكائن الحالي من API المزوّد قبل تعديل الحالة المحلية.