
الميزات الرئيسية
توفر webhooks التسليم في الوقت الفعلي مع أمان مدمج، وعمليات إعادة محاولة تلقائية، وتصفية للأحداث. تتضمن جميع SDKs الرسمية أدوات مساعدة للتحقق من التوقيعات، كما توفر لوحة المعلومات أدوات للاختبار والمراقبة وإعادة التشغيل.البدء
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
موصلات التكامل
وجّه أحداث webhook مباشرةً إلى خدمات خارجية باستخدام موصلات التكامل، مما يلغي الحاجة إلى إنشاء معالجات webhook مخصصة وصيانتها.كيفية عمل الموصلات
يحوّل الموصل أحداث Dodo Payments إلى التنسيق الذي تتوقعه الوجهة. وتعتمد التفاصيل التي تقدمها على الوجهة:إعداد موصل
عند إنشاء نقطة نهاية أو تعديلها، اختر موصلًا وستعرض اللوحة الجانبية تعليمات الإعداد الخاصة بالوجهة. اختبر التحويل قبل الحفظ للتأكد من تحويل الأحداث بشكل صحيح.تهيئة الأحداث المشترك بها
هيّئ الأحداث التي تستلمها كل نقطة نهاية webhook.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment وsubscription وdispute). حدد مربعات الاختيار بجوار الأحداث التي تريد استلامها. يمكنك اختيار أحداث فردية أو مورد كامل أو المزج بينهما.Save Configuration
كتالوج الأحداث
انتقل إلى Developer → Webhooks وافتح علامة التبويب Event catalog لرؤية كل نوع من الأحداث التي يمكن لـ Dodo Payments إرسالها. اختر حدثًا لعرض مخططه وحمولة نموذجية.Webhook Events Guide
تسليم Webhook
مهلات الانتظار
تحتوي Webhooks على مهلة 30 ثانية لكلٍّ من عمليات الاتصال والقراءة. عالج Webhooks بشكل غير متزامن عبر إرجاع رمز الحالة200 فورًا، ثم عالج الحدث في الخلفية.
عمليات إعادة المحاولة التلقائية
تُعاد محاولة عمليات التسليم الفاشلة باستخدام تأخير أُسّي، بحد أقصى 8 محاولات إجمالًا:Idempotency
تتضمن كل webhook رأسwebhook-id فريدًا. خزّن هذا المعرّف لاكتشاف الأحداث المكررة وتخطيها، إذ قد تؤدي إعادة المحاولة إلى تسليم الحدث نفسه عدة مرات.
ترتيب الأحداث
قد تصل الأحداث بترتيب غير صحيح بسبب عمليات إعادة المحاولة أو ظروف الشبكة. تتضمن كل webhook حقلtimestamp؛ استخدمه لترتيب الأحداث إذا كان تطبيقك يتطلب ذلك. تتلقى دائمًا أحدث حالة للبيانات عند التسليم.
تأمين Webhooks
تحقق دائمًا من حمولات Webhooks واستخدم HTTPS.التحقق من التوقيعات
تتضمن كل webhook رأسwebhook-signature: وهو توقيع HMAC SHA256 للحمولة والطابع الزمني، موقّع باستخدام مفتاحك السري.
التحقق باستخدام SDK (موصى به)
تتضمن جميع SDKs الرسمية أدوات مساعدة مدمجة. عيّنDODO_PAYMENTS_WEBHOOK_KEY عند تهيئة العميل، ثم استدعِ unwrap() للتحقق من الحمولة وتحليلها. تتوفر طريقتان:
unwrap— يتحقق من التوقيع باستخدام مفتاح webhook السري، ثم يحلل الحمولة.unsafe_unwrap— يحلل الحمولة دون التحقق منها. استخدمه للاختبار فقط.
unwrap / unsafeUnwrap في TypeScript، وunwrap / unsafe_unwrap في Python، وUnwrap / UnsafeUnwrap في Go.
التحقق اليدوي (بديل)
إذا لم تكن تستخدم SDK، فتحقق من التوقيع بنفسك:- أنشئ المحتوى الموقّع بضم
webhook-idوwebhook-timestampونص الطلب الخام باستخدام النقاط:{id}.{timestamp}.{body}. استخدم النص الخام تمامًا كما استلمته، قبل أي تحليل لـ JSON. - خذ سر webhook. إذا بدأ بـ
whsec_، فأزل تلك البادئة، ثم فك ترميز Base64 للجزء المتبقي للحصول على مفتاح التوقيع. - احسب HMAC-SHA256 للمحتوى الموقّع باستخدام مفتاح التوقيع، ثم شفّر النتيجة بترميز Base64.
- يحتوي الرأس
webhook-signatureعلى توقيع واحد أو أكثر مفصولة بمسافات، وكل توقيع بالصيغةv1,<base64-signature>. يكون الطلب صالحًا إذا تطابق أي توقيعv1مع توقيعك. قارن باستخدام دالة ذات وقت ثابت. - ارفض الطلب إذا كان
webhook-timestampبعيدًا جدًا عن الوقت الحالي، لمنع هجمات إعادة التشغيل. تسمح مكتبات Standard Webhooks بخمس دقائق.
عناوين IP المصدر
يُعد التحقق من التوقيع طريقة المصادقة المدعومة. فهو يثبت أن الطلب وُقّع باستخدام سر webhook الخاص بك، وهو أمر لا يستطيع فحص مستوى الشبكة إثباته. تأتي عمليات تسليم Webhooks من مجموعة من عناوين IP التي تتغير بمرور الوقت. لا تعتمد على قوائم السماح لعناوين IP للمصادقة. تحقّق دائمًا من الرأسwebhook-signature بدلًا من ذلك، كما هو موضح في التحقق من التوقيعات.
إذا كان جدار الحماية يتطلب قائمة سماح:
- لا تضع العناوين في التعليمات البرمجية بشكل دائم. تتغير النطاقات بمرور الوقت، وقد تحظر القواعد القديمة عمليات التسليم بصمت.
- اطلب النطاقات الحالية من support@dodopayments.com قبل تقييد جدار الحماية.
- راقب إشعارات التغيير. عند تغير عناوين التسليم، نُخطر التجار المتأثرين عبر البريد الإلكتروني — طبّق التحديثات قبل التاريخ المحدد.
- أبقِ التحقق من التوقيع مفعّلًا بغض النظر عن أي قواعد شبكة تضيفها.
الاستجابة إلى Webhooks
يجب أن يعيد معالج webhook القيمة2xx status code لتأكيد الاستلام. تُعامل أي استجابة أخرى على أنها فشل، وستُعاد محاولة webhook.
أفضل الممارسات
- استخدم HTTPS فقط. تكون نقاط نهاية HTTP عرضة للاعتراض.
- استجب فورًا. أعد رمز الحالة
200على الفور، ثم عالج الحدث بشكل غير متزامن. - طبّق Idempotency. استخدم الرأس
webhook-idلاكتشاف الأحداث المكررة وتخطيها. - أمّن سرك. خزّن
DODO_PAYMENTS_WEBHOOK_KEYفي متغيرات البيئة أو مدير أسرار، وليس في نظام التحكم بالإصدارات.
بنية حمولة Webhook
تنسيق الطلب
الرؤوس
نص الطلب
payment.succeeded وsubscription.active).مثال على الحمولة
Event Types
Event Payloads
Handle Payment Failures
payment.failed واسترد المدفوعات المرفوضةاختبار Webhooks
إرسال حدث نموذجي
اختبر تكامل webhook مباشرةً من لوحة التحكم:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.مثال على التنفيذ
تطبيق Express.js كامل مع التحقق من webhook ومعالجته:اختبار Webhooks باستخدام CLI
يحتوي Dodo Payments CLI على أمرين لاختبار Webhooks أثناء التطوير المحلي.الاستماع إلى Webhooks المباشرة محليًا
أعد توجيه أحداث webhook الحقيقية من حساب وضع الاختبار إلى خادم التطوير المحلي:http://localhost:3000/webhook)، مع الحفاظ على جميع الرؤوس لاختبار التحقق من التوقيع.
dodo login وحدد Test Mode أولًا.تشغيل أحداث Webhook وهمية
أرسل حمولات webhook وهمية إلى أي نقطة نهاية دون إنشاء معاملات حقيقية:subscription.past_due أو subscription.unpaused. راجع Supported Webhook Events للقائمة الدقيقة.
CLI Webhook Testing Docs
الإعدادات المتقدمة
توفر علامة التبويب Advanced خيارات إعداد إضافية لضبط سلوك نقطة نهاية webhook بدقة.تحديد معدل الطلبات (Throttling)
تحكم في معدل تسليم أحداث webhook إلى نقطة النهاية الخاصة بك. لا يُطبّق حد للمعدل على Webhooks افتراضيًا، ويتم تسليم الأحداث فور حدوثها.Open Advanced Tab
Configure Rate Limit
Set Your Limit
الرؤوس المخصصة
أضف رؤوس HTTP مخصصة إلى جميع طلبات webhook المُرسلة إلى نقطة النهاية. يفيد ذلك في المصادقة أو التوجيه أو إضافة البيانات الوصفية.Add Headers
Add Multiple Headers
التحويلات
تتيح لك التحويلات تعديل حمولة webhook وإعادة توجيهها اختياريًا إلى عنوان URL مختلف. استخدم التحويلات من أجل:- تعديل بنية الحمولة قبل المعالجة
- توجيه Webhooks إلى نقاط نهاية مختلفة استنادًا إلى المحتوى
- إضافة الحقول إلى الحمولة أو إزالتها منها
- تحويل تنسيقات البيانات
Enable Transformations
Configure Transformation
handler().Test Transformation
مراقبة سجلات Webhooks
توفر علامة التبويب Logs إمكانية الاطلاع على حالة تسليم webhook.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- حمولة webhook الكاملة
- كل محاولة تسليم مع رمز الاستجابة والمدة
- الطابع الزمني لكل محاولة
- أي رسائل خطأ من نقطة النهاية الخاصة بك
مراقبة النشاط
انتقل إلى Developer → Webhooks وافتح علامة التبويب Activity للاطلاع على أداء التسليم عبر نقاط النهاية الخاصة بك. يعرض نشاط التسليم المحاولات بمرور الوقت، مجمّعةً على شكل Attempts per 5 minutes أو Attempts per hour أو Attempts per day حسب النافذة. يُقسّم كل شريط حسب النتيجة، ويؤدي تمرير المؤشر فوق مقطع إلى عرض الحالة وعدد المحاولات ونسبته من الإجمالي. في نقطة النهاية، تلخّص Delivery stats (last 24h) في علامة التبويب Overview المعلومات نفسها لليوم السابق.إعادة تشغيل الرسائل واستردادها
تعتمد طريقة إعادة دفع الرسالة على عدد الرسائل التي تحتاج إليها:- رسالة واحدة — افتحها من علامة التبويب Logs واستخدم إجراء Replay في المحاولة.
- نطاق من الرسائل — افتح نقطة النهاية، إذ تعمل أوضاع المعالجة المجمعة على نقطة نهاية واحدة في كل مرة.
إعادة التشغيل دفعةً واحدة
افتح نقطة النهاية من Developer → Webhooks. تتوفر ثلاثة أوضاع، ويعمل كل منها على نقطة النهاية وحدها:Open More Actions
Set the Range
Start the Run