عندما لا يصل webhook أبدًا

اعمل خلال المشكلة بالترتيب - سجل التسليم، واسم الحدث، والجدار الناري، والتوقيع. يخبرك تبويب Deliveries ما إذا كانت Didit قد أرسلته، مما يقسم المشكلة إلى نصفين فورًا.

بقلم دعم Didit · آخر تحديث 19 أغسطس 2026

#الخطوة 1: هل حاولت Didit إرسال التسليم؟

افتح الوجهة في API & Webhooks وانظر إلى تبويب Deliveries. كل محاولة مسجَّلة على حدة، مع استجابتها.

1234

1. يخبرك Last sent ما إذا كانت Didit قد حاولت الإرسال أصلًا.
2. يعرض View stats المحاولات والإخفاقات لتلك الوجهة.
3. يفصل تسليم تجريبي بين نقطة نهايتك والحدث نفسه.
4. يمكن تعطيل وجهة تستمر في الفشل ريثما تُصلحها.

هذا الفحص الواحد يقسم المشكلة إلى نصفين:

• لا توجد محاولة مسجَّلة ← لم يُولَّد الحدث أبدًا لتلك الوجهة. انتقل إلى الخطوة 2.
• محاولة مسجَّلة، فشلت ← أرسلته Didit ورفضه جانبك أو لم يستقبله. انتقل إلى الخطوة 3.
• محاولة مسجَّلة، 2xx ← تم تسليمه بنجاح. المشكلة داخل المعالج لديك، لا في التسليم.

#الخطوة 2: لم تُسجَّل أي محاولة

بترتيب الاحتمال:

1. الحدث غير مشترك فيه. لا يوجد رمز بدل عام (wildcard) - يجب إدراج كل عائلة أحداث صراحةً. والاسم غير الموجود (session.status.updated، kyc.completed) لا يستقبل شيئًا دون تنبيه. تحقق من قائمة الأحداث.
2. تطبيق خاطئ. الوجهات تخص تطبيقًا معينًا. إذا كانت جلساتك تعمل ضمن تطبيق مختلف عن الوجهة، فلن يصلها أي حدث أبدًا. هذا هو السبب الأكثر شيوعًا عندما يبدو كل شيء مُعدًّا بشكل صحيح.
3. لم يتغيّر شيء فعليًا. تُطلَق الأحداث عند التغيير. جلسة لم تتحرك، أو إعادة فحص AML مستمر لم يجد شيئًا فوق العتبة، تُنتج بشكل صحيح لا حدث.
4. الحالة التي تنتظرها لم تحدث بعد. جلسة في حالة In Progress لم تنتهِ. انظر عندما لا تنتهي جلسة أبدًا.

#الخطوة 3: حاولت عملية التسليم وفشلت

خطأ 404 يعني أن الطلب وصل إلى شيء لا يملك مسارك. تحقق من:

• المسار الدقيق، بما في ذلك الشرطة المائلة الأخيرة. إطار عمل يعيد توجيه /hook إلى /hook/ يمكن أن يحوّل نقطة نهاية عاملة إلى 404 أو جسم مفقود.
• ما إذا كان الرابط عامًا. مضيف محلي أو تجريبي غير قابل للوصول من الإنترنت يفشل بهذه الطريقة.
• ما إذا كان وكيل، أو موازن تحميل، أو موجِّه قائم على المسار أمام تطبيقك يرسل ذلك المسار إلى مكان آخر.

خطأ 5xx يعني أن المعالج لديك رمى استثناءً. سجّل الجسم الخام قبل تحليله لترى ما استقبله فعليًا.

انتهاء المهلة يعني أنك لم تستجب بسرعة كافية. أعد 2xx أولًا، ثم عالج بعد ذلك.

لا شيء إطلاقًا / رفض الاتصال يعني أن حافتك حجبته. تُسلِّم Didit من عنوان IP الثابت 18.203.201.92 بعميل مستخدم DiditWebhook/2.0. إذا كنت خلف Cloudflare أو جدار حماية بموقف رفض افتراضي، اسمح بذلك العنوان لاسم المضيف المستقبِل.

#الحالة الكلاسيكية: التسليم الآلي يعطي 404 لكن Resend يعمل

هذه تتكرر بما يكفي لتستحق اسمًا. يفشل التسليم الآلي بخطأ 404، ثم النقر على Resend لنفس الحدث ينجح.

هذا التوليف يعني أن الحمولة ونقطة نهايتك سليمتان كلاهما - إذن الفارق هو التوقيت أو المسار، لا المحتوى. تحقق من:

• نشر أو إعادة تشغيل في لحظة التسليم الأصلي. ينجح Resend لاحقًا لأن التطبيق يعمل مجددًا.
• بدء بارد تجاوز مهلة منصتك - شائع في serverless مع أول استدعاء بطيء.
• توجيه قائم على المسار تغيّر بين المحاولتين، أو قاعدة لا تطابق سوى بعض الطلبات.
• تحديد معدل أو حماية من الروبوتات على حافتك سمحت بمرور إعادة الإرسال اليدوية لأنها وصلت وحدها لا ضمن دفعة.

يحتوي تبويب Deliveries على كلتا المحاولتين بطوابعهما الزمنية - قارنهما بسجلات النشر والأخطاء لديك في تلك الدقيقة.

#فشل التحقق من التوقيع

يكاد يكون دائمًا واحدًا من ثلاثة أشياء:

1. جزّأت JSON مُعاد التسلسل. جزّئ بـ HMAC بايتات الجسم الخام للطلب تمامًا كما وصلت. التحليل ثم إعادة التسلسل يغيّر المسافات وترتيب المفاتيح، ولن يتطابق التوقيع. تحتاج معظم أطر العمل إلى إعداد صريح لتمنحك الجسم الخام.
2. السر الخاطئ. سر التوقيع لكل وجهة، وهو ليس مفتاح API الخاص بك. لوجهتين سرّان مختلفان.
3. افتراض ترميز خاطئ. إذا لم تكن متأكدًا مما إذا كان السر يُستخدم كسلسلة حرفية أو يُفكّ ترميزه أولًا، لا تخمّن - اتبع مرجع التحقق من التوقيع بدقة، وسجّل الجسم الخام أثناء التصحيح حتى تتمكن من المقارنة.

#محاولتان ليستا طابورًا

عند 5xx، أو 404، أو انتهاء مهلة، أو فشل اتصال، تعيد Didit المحاولة مرتين - بعد نحو دقيقة واحدة ثم بعد 4 دقائق أخرى - ثم تُسقط عملية التسليم. إذا كانت نقطة نهايتك معطلة لأطول من ذلك، فتلك الأحداث ضاعت نهائيًا.

ابنِ مسار تسوية: عند بدء التشغيل، استقصِ نقطة نهاية القرار عن أي جلسة لا تملك لها حالة نهائية. عامل webhooks كمسار سريع والاستقصاء كخط دفاع احتياطي.

#الاختبار دون تشغيل عمليات تحقق

يرسل Try Webhook في صفحة الوجهة حدثًا مكتمل التكوين من أيّ نوع تختاره - مقبول، مرفوض، قيد المراجعة، KYB، كيان، معاملة. استخدمه لإثبات أن نقطة نهايتك، وفحص التوقيع، والمعالج لديك تعمل قبل أن تعتمد عليها جلسة حقيقية.

sandbox هو النصف الآخر من هذا: تُصدر جلسة sandbox أحداث webhook حقيقية بـ "environment": "sandbox"، لذا يمكنك تجربة المسار كاملًا من طرف إلى طرف مجانًا. انظر الاختبار في sandbox.