وقت القراءة المقدر : 6 min · تاريخ النشر
اكتب عقد الحدث
توثيق المنتج وأنواع الأحداث المتوقعة والحقول المطلوبة والتشغيل المشغل. وصف نتائج الإنشاء والتغيير والحذف عند الاقتضاء. يجب ألا يأذن الإخطار ضمنيًا بكل إجراء ممكن.
اختر معرّف تتبع ومصدر موثوق للتشاور عندما تكون غير مؤكد. صف كيف يتم الكشف عن حالات الفشل في المنتج أو المتلقي. وثائق التكامل تحمل القواعد والمالكين ؛ الأسرار تنتمي إلى آلية تأمين المشروع.
في n8n، يختلف استخدام عنواني webhook للاختبار والإنتاج. الاستماع إلى حدث تجريبي لا يجهز الاستقبال المستمر؛ يسجل عنوان الإنتاج عند نشر سير العمل. افحص العنوان المضبوط لدى المرسل وراجع تشغيلات الإنتاج في Executions.
يغير نمط الرد معنى تأكيد الاستلام. مع Immediately، يعلن الرد بدء سير العمل، ولا يؤكد تحديث الطلب أو سجل العميل. اربط معرف الحدث بالتشغيل والحالة النهائية في الخدمة المستهدفة قبل إعلان نجاح العملية.
مرّر الجدول أفقيًا لقراءة جميع الأعمدة. باستخدام لوحة المفاتيح، انقل التركيز إلى الجدول ثم استخدم مفاتيح الأسهم.
| نقطة الفحص | ملاحظة محتملة | الدليل المنتظر |
|---|---|---|
| عنوان الاختبار | ظهور الحدث أثناء الاستماع التجريبي | العنوان والبيئة المستخدمان للاختبار |
| عنوان الإنتاج | سير عمل منشور وتشغيل مسجل | معرف تشغيل مرتبط بالحدث المستلم |
| رد Immediately | بدأ سير العمل | الحالة النهائية والعملية المتوقعة في الخدمة المستهدفة |
تحقق قبل بدء العملية
مستندات Github التحقق من صحة توقيع التسليم باستخدام السر الذي تم تكوينه والحمولة المستلمة. اتبع الآلية الموثقة للمزود الفعلي ؛ لا ينبغي نسخ الرؤوس والخوارزميات والتنسيقات من خدمة أخرى عن طريق القياس.
التحقق من الأصل بشكل منفصل والتحقق من صحة المخطط وترخيص التشغيل. اختبار المحتوى المتغير ونوع حدث غير متوقع وحقل مفقود. يجب أن تبدأ معالجة الأعمال فقط بعد عناصر التحكم المطلوبة لحالة الاستخدام.
تكرار الخطة والانقطاعات
تعريف التعامل مع Idempotent: يجب ألا يؤدي التسليم المتكرر المعترف به إلى إنشاء أمرين أو إخطارين نهائيين. تكرار الاختبار قبل وأثناء وبعد المعالجة وانقطاع بين الخطوات. تعتمد الآلية على التشغيل والتخزين المعنيين.
تحقق من ضمانات طلب المزود وإعادة التسليم بدلاً من افتراض الوصول الفوري لمرة واحدة. احتفظ بقائمة انتظار من العمل الذي يتطلب مراجعة وطريقة للتوفيق بينه وبين المصدر. يجب أن تتوافق الاستجابة الفنية الإيجابية مع حالة معالجة محددة.
ترتيب المراقبة والانتعاش
سجل معرف الحدث والحالة والخطأ المفيد مع تقليل البيانات. حدد من يراقب الإخفاقات ، وكيف تتم إعادة محاولة الأحداث المصرح بها وكيفية إعادة المحاولة تجنب تكرار العمل المكتمل.
مقاطعة جهاز الاستقبال في بيئة اختبار واستعادته. تحقق من اللحاق بالركب والتوفيق بين نتائج الأعمال المتوقعة. تقديم عقد حدث ، ودفعة اختبار ، وتاريخ المعالجة وإجراءات الاسترداد التي يمكن للفريق استخدامها.
التوثيق الأساسي: GitHub - التحقق من عمليات تسليم خطاف الويب.
مثال افتراضي: يؤدي DEMO-E41 إلى كتابة عمل واحدة في قاعدة بيانات. يجمع الاتفاق هذه الكتابة ووضع علامة معالجة الحدث في المعاملة نفسها؛ ويضبط مفتاح فريد يجمع المنتج والمعرّف المعالجات المتزامنة. اختبر الانقطاع قبل COMMIT وبعده. تعثر الاستعادة بعد تثبيت المعاملة على العمل المنجز بدل إضافة أثر ثانٍ. تسجيل «تم الاستلام» في سجل منفصل لا يمنح هذا الضمان.
في GitHub تحتفظ إعادة التسليم بقيمة X-GitHub-Delivery؛ لذا لا تصبح المحاولة الجديدة حدثًا جديدًا لهذا السبب وحده. تحقق من سلوك كل منتج آخر على حدة. يوضح DEMO-E42 حدًا مختلفًا: تنتهي مهلة استدعاء خدمة خارجية دون استجابة. لا تثبت المعاملة المحلية إن كانت الخدمة قد تصرفت؛ طابق مرجعها وضمانات إعادة المحاولة الموثقة قبل تكرار الإجراء.
مرّر الجدول أفقيًا لقراءة جميع الأعمدة. باستخدام لوحة المفاتيح، انقل التركيز إلى الجدول ثم استخدم مفاتيح الأسهم.
| حالة الاختبار | الأثر المثبت للعمل | الاستعادة المتوقعة |
|---|---|---|
| DEMO-E41 قبل COMMIT مع إلغاء المعاملة | 0 أثر مثبت | الاستعادة وفق السجل المعاملي |
| DEMO-E41 بعد COMMIT | 1 أثر والحدث معلّم كمعالج | استرجاع النتيجة المثبتة سابقًا |
| إعادة تسليم DEMO-E41 | ما زال المجموع 1 أثر | التعرف على المفتاح وعدم تكرار الكتابة |
| DEMO-E42: استدعاء خارجي دون استجابة | نتيجة مجهولة: قد يوجد 0 أو 1 أثر | المطابقة مع الخدمة وتجنب التكرار الأعمى |
- GitHub : Webhook Best Practices
GitHub، تمت مراجعته في 22 أكتوبر 2026: حفظ المعرّف عند إعادة التسليم. DEMO-E41 وDEMO-E42 معرّفان مختصران لحدثين افتراضيين.
- PostgreSQL : Transactions
PostgreSQL، تمت مراجعته في 22 أكتوبر 2026: معاملات قاعدة البيانات، دون ضمان شامل للاستدعاء الخارجي.
المستندات المرجعية
- Stripe : Webhooks · مصدر تمت مراجعته
- n8n : Webhook node · مصدر تمت مراجعته
- GitHub - التحقق من عمليات تسليم خطاف الويب
تاريخ تحديث المحتوى
مراجع موثقة لهذا الموضوع
| المرجع | القيمة أو الصيغة | النطاق |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | لا يسمح JSON القياسي بالتعليقات أو الفاصلة الختامية؛ وتستخدم السلاسل علامات اقتباس مزدوجة. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | يربط فرق التوقيت الصريح الوقت المحلي بـUTC؛ هذا المثال ليس موعدًا. |
تشير التواريخ إلى الاطلاع على المراجع. هذه المعلومات ليست تدقيقاً للموقع ولا إعلاناً شاملاً عن المطابقة.
