تلقَّ إشعارات فورية عند وقوع الأحداث في <Frame>. أتمت سير العمل وحافظ على مزامنة أنظمتك من خلال تسليم الأحداث فورًا.
توفر Webhooks إشعارات فورية عند وقوع أحداث محددة في حسابك على Dodo Payments. استخدم Webhooks لأتمتة سير العمل، وتحديث قاعدة بياناتك، وإرسال الإشعارات، والحفاظ على مزامنة أنظمتك.
يتبع تنفيذ Webhook لدينا مواصفة Standard Webhooks، مما يضمن التوافق مع أفضل ممارسات المجال ومكتبات Webhook الحالية.
تمت إعادة بناء بوابة webhooks الخاصة بـ Dodo Payments لتوفير تجربة لوحة تحكم أصلية. لم تتغير نقاط النهاية الحالية أو أسرار التوقيع أو التحقق من التوقيع أو أسماء الأحداث أو حمولات webhook. لا يلزم إجراء أي عمل على التكامل.
ضمن نقطة نهاية فردية — علامة التبويب Overview، التي تتضمن إحصاءات التسليم وسر التوقيع وReplay history، بالإضافة إلى علامتي التبويب Testing وAdvanced وإجراءات إعادة التشغيل المجمّعة.
ضمن رسالة — تُفتح من علامة التبويب Logs، حيث يمكن إعادة تشغيل كل محاولة تسليم على حدة دون فتح نقطة النهاية.
1
Access Webhook Settings
انتقل إلى لوحة تحكم Dodo Payments ثم إلى Developer → Webhooks.
2
Create Webhook Endpoint
انقر على Add endpoint لفتح اللوحة الجانبية لإنشاء نقطة نهاية.
3
Enter Endpoint URL or Choose Integration
أدخل عنوان URL الذي تريد استقبال أحداث webhook عليه، أو حدد موصل تكامل لتوجيه الأحداث إلى خدمة تابعة لجهة خارجية (Slack وDiscord وZapier وResend وغير ذلك).
4
Select Events to Receive
اختر الأحداث المحددة التي يجب أن تستمع إليها نقطة النهاية. تُنظّم الأحداث في شجرة قابلة للبحث ومجمّعة حسب المورد. يمكنك تحديد أحداث فردية أو مورداً رئيسياً لاستقبال جميع الأحداث المرتبطة به.
ستؤدي الأحداث المحددة فقط إلى تشغيل webhooks لنقطة النهاية، مما يساعدك على تجنب حركة المرور والمعالجة غير الضروريتين.
5
Create Endpoint
انقر على Create endpoint لحفظ إعداداتك.
6
Get Secret Key
يظهر سر توقيع webhook الخاص بك في علامة التبويب Overview لنقطة النهاية. ستستخدمه للتحقق من صحة webhooks المستلمة.
احرص على أمان مفتاح سر webhook ولا تكشفه مطلقاً في التعليمات البرمجية من جهة العميل أو المستودعات العامة.
7
Rotate Secret (Optional)
عند الحاجة، يمكنك تدوير سر webhook لتعزيز الأمان. انقر على Rotate secret بجانب السر في علامة التبويب Overview.
سيؤدي تدوير السر إلى إبطال السر الحالي واستبداله بآخر جديد. سيظل السر القديم صالحاً خلال الساعات الأربع والعشرين التالية فقط. بعد ذلك، سيفشل التحقق باستخدام السر القديم.
استخدم تدوير السر بشكل دوري أو فوراً إذا اشتبهت في تعرض سرك الحالي للاختراق.
بدلاً من إنشاء مستقبِل webhook خاص بك، يمكنك توجيه أحداث webhook مباشرةً إلى خدمات تابعة لجهات خارجية باستخدام موصلات التكامل. يلغي ذلك الحاجة إلى كتابة معالجات webhook مخصصة للمنصات الشائعة وصيانتها.
يعرض محدد الموصلات في لوحة التحكم المجموعة الكاملة المتاحة حالياً لنشاطك التجاري، لذا تعامل مع الجدول أعلاه على أنه الوجهات التي تتوفر لها تعليمات إعداد خطوة بخطوة، وليس قائمة شاملة. راجع External Integrations لمعرفة ما يمكن لكل وجهة فعله بعد وصول الأحداث إليها.
اختر موصلاً أثناء إنشاء نقطة نهاية أو تعديلها، وستعرض اللوحة الجانبية تعليمات إعداد مخصصة لتلك الوجهة — مثل كيفية إنشاء عنوان URL لـ Incoming webhook في Slack أو مكان العثور على مفتاح Resend API. قبل الحفظ، شغّل اختبار تحويل الموصل للتأكد من تحويل الحدث بشكل صحيح للوجهة.
استخدم موصلاً للوصول إلى وجهة مدعومة دون كتابة تعليمات برمجية. إذا كنت تحتاج إلى منطق مخصص، فاستخدم نقطة نهاية قياسية مع transformation بدلاً من ذلك.
يمكنك إعداد الأحداث المحددة التي يجب أن تستقبلها كل نقطة نهاية webhook.
1
Navigate to Webhook Endpoints
انتقل إلى لوحة تحكم Dodo Payments ثم إلى Developer → Webhooks.
2
Select Your Endpoint
انقر على نقطة نهاية webhook التي تريد إعدادها.
3
Open Event Configuration
انقر على Edit لفتح اللوحة الجانبية لإعداد نقطة النهاية.
4
Browse Event Types
يعرض محدد نوع الحدث جميع أحداث webhook المتاحة في شجرة قابلة للبحث ومجمّعة حسب المورد (مثل payment وsubscription وdispute). استخدم شريط البحث للعثور سريعاً على أحداث محددة بالاسم أو الكلمة المفتاحية.
5
Select Events
حدد المربعات بجانب الأحداث التي تريد استقبالها. يمكنك:
تحديد أحداث فردية (مثل payment.succeeded وpayment.failed)
تحديد مورداً رئيسياً لاستقبال جميع الأحداث المرتبطة به
الجمع بين أحداث محددة وفقاً لاحتياجاتك
6
Save Configuration
انقر على Save لتطبيق تغييراتك، أو Cancel لتجاهل التعديلات.
إذا ألغيت تحديد جميع الأحداث، فلن تستقبل نقطة نهاية webhook أي إشعارات. احرص على تحديد الأحداث التي يحتاج إليها تطبيقك للعمل بشكل صحيح على الأقل.
انتقل إلى Developer → Webhooks وافتح علامة التبويب Event catalog. تسرد هذه العلامة كل نوع من الأحداث التي يمكن لـ Dodo Payments إرسالها، حتى تتمكن من معرفة المتاح قبل اشتراك نقطة نهاية فيه. حدد حدثاً لعرض مخططه ومثال على حمولته، وهي أسرع طريقة للتحقق من بنية حقل تنوي قراءته.
Webhook Events Guide
تصفح الأحداث نفسها بوصفها وثائق مرجعية، مجمّعة حسب المورد.
عند فشل تسليم webhook، يعيد Dodo Payments المحاولة تلقائياً باستخدام تأخير أُسّي لتجنب إغراق نظامك.
المحاولة
التأخير
الوصف
1
فوراً
تحدث إعادة المحاولة الأولى فوراً
2
5 ثوانٍ
المحاولة الثانية بعد تأخير قصير
3
5 دقائق
المحاولة الثالثة مع زيادة التأخير
4
30 دقيقة
المحاولة الرابعة مع استمرار التأخير
5
ساعتان
المحاولة الخامسة بتأخير ممتد
6
5 ساعات
المحاولة السادسة بتأخير أطول
7
10 ساعات
المحاولة السابعة بأقصى تأخير
8
10 ساعات
المحاولة النهائية - يُعلّم webhook كفاشل إذا لم تنجح
حد أقصى 8 محاولات إعادة لكل حدث webhook. على سبيل المثال، إذا فشل webhook ثلاث مرات قبل نجاحه، فسيكون إجمالي وقت التسليم نحو 35 دقيقة و5 ثوانٍ من المحاولة الأولى.
استخدم لوحة تحكم Dodo Payments لإعادة محاولة رسائل فردية يدوياً أو استرداد جميع الرسائل الفاشلة بشكل مجمّع في أي وقت.
يُعد التحقق من التوقيع الطريقة المدعومة لمصادقة webhook. فهو يثبت أن الطلب وُقّع باستخدام سر webhook الخاص بك، وهو أمر لا يمكن لفحص على مستوى الشبكة إثباته.تُرسل عمليات تسليم webhook من مجموعة من عناوين IP المصدر التي تنتمي إلى بنية التسليم التحتية لدينا. تتغير هذه المجموعة من وقت لآخر، لذا تعامل مع العناوين باعتبارها تفاصيل تشغيلية وليست خاصية ثابتة للتكامل.
لا تستخدم قائمة سماح لعناوين IP المصدر كآلية للمصادقة. فقائمة السماح توضح فقط مصدر الطلب، ولا تثبت أنه حقيقي أو لم يتم تعديله — تحقّق من header webhook-signature في كل طلب، كما هو موضح في التحقق من التوقيعات.
إذا كانت بنيتك التحتية خلف جدار حماية يتطلب قائمة سماح صريحة، فضع الأمور التالية في الاعتبار:
لا تُضمّن العناوين في الشيفرة بشكل دائم. تُضاف النطاقات وتُزال بمرور الوقت، وقد تؤدي قاعدة قديمة إلى حظر عمليات التسليم دون إشعار.
اطلب النطاقات الحالية من support@dodopayments.com قبل تقييد جدار الحماية، لضمان استخدامك قائمة محدثة.
راقب إشعارات التغيير. عند تغيير عناوين التسليم، نُخطر التجار المتأثرين عبر البريد الإلكتروني — طبّق هذه التحديثات قبل التاريخ المحدد لتجنب فقدان عمليات التسليم.
أبقِ التحقق من التوقيع مفعّلًا بغض النظر عن أي قواعد شبكة تضيفها.
في منصات serverless والاستضافة المُدارة، غالبًا ما تكون تصفية IP الواردة غير متاحة أو غير عملية للصيانة. ويُعد التحقق من التوقيع عنصر التحكم الصحيح في هذه البيئات، ولا تكون هناك حاجة إلى قائمة سماح.
يُعامل التسليم المحظور مثل أي فشل آخر، وتتم إعادة محاولته وفق الجدول الموضح في إعادة المحاولات التلقائية. إذا تسببت قواعد جدار الحماية في فشل عمليات التسليم، يمكنك إعادة إرسالها بعد إصلاح القواعد — راجع إعادة تشغيل الرسائل واستردادها.
نوع المورد. أحد الأنواع التالية: Payment أو Subscription أو Refund أو Dispute أو LicenseKey أو CreditLedgerEntry أو CreditBalanceLow أو AbandonedCheckout أو DunningAttempt أو EntitlementGrant أو Payout.
تختلف الحقول الإضافية حسب نوع الحدث. راجع وثائق الحدث المحدد للاطلاع على المخططات الكاملة.
أعد توجيه أحداث webhook الحقيقية من حساب وضع الاختبار إلى خادم التطوير المحلي في الوقت الفعلي:
dodo wh listen
يفتح CLI اتصال WebSocket بـ Dodo Payments ويعيد توجيه كل حدث webhook إلى نقطة النهاية المحلية (مثل http://localhost:3000/webhook)، مع الحفاظ على جميع Headers، بما فيها Headers الخاصة بالتوقيع لاختبار التحقق.
يعمل المستمع فقط مع مفاتيح API الخاصة بـ test mode. شغّل dodo login واختر Test Mode قبل استخدام هذا الأمر.
أرسل payloads وهمية لـ webhook إلى أي نقطة نهاية دون إنشاء معاملات حقيقية:
dodo wh trigger
تتيح لك هذه الأداة التفاعلية اختيار نوع حدث وإرسال payload وهمي واقعي إلى نقطة النهاية الخاصة بك. وتستمر في حلقة حتى تتمكن من اختبار أحداث متعددة في جلسة واحدة.يغطي أمر التشغيل جميع أنواع الأحداث البالغ عددها 47 التي يسلّمها Dodo Payments، بما في ذلك عائلات الاشتراكات والمدفوعات والمبالغ المستردة والنزاعات ومفاتيح الترخيص وعمليات الدفع والائتمانات وعمليات الدفع المتروكة والتحصيل والمنح الخاصة بالاستحقاقات — راجع أحداث Webhook المدعومة للاطلاع على القائمة الدقيقة.
إن payloads الوهمية لـ webhook من dodo wh trigger غير موقّعة. استخدم unsafe_unwrap() بدلًا من unwrap() في معالج webhook الخاص بك أثناء الاختبار فقط.
توفر علامة تبويب Logs رؤية شاملة لحالة تسليم webhook، ما يتيح لك مراقبة أحداث webhook وتصحيح أخطائها وإدارتها بفعالية.
1
Navigate to Logs Tab
انتقل إلى Developer → Webhooks وافتح علامة تبويب Logs.
2
Browse Delivery History
اعرض جدولًا يضم جميع محاولات تسليم webhook، مع أعمدة لنوع الحدث، ومعرّف الرسالة، ومعرّف الحدث، ووقت الإرسال، ووقت المحاولة، ورمز الاستجابة، والمدة.
3
Search and Filter
استخدم شريط البحث للعثور على رسائل محددة حسب المعرّف أو نوع الحدث. ويمكنك التصفية حسب الحالة (Succeeded أو Failed أو Pending وما إلى ذلك) للتركيز على الأحداث التي تحتاج إلى التحقيق فيها.
4
View Message Details
انقر على أي رسالة لفتح صفحة تفاصيل الرسالة، التي تعرض:
Payload الكامل لـ webhook
كل محاولة تسليم مع رمز الاستجابة والمدة
الطابع الزمني لكل محاولة
أي رسائل خطأ من نقطة النهاية الخاصة بك
تتضمن كل محاولة إجراء Replay، حتى تتمكن من إعادة دفع تلك الرسالة دون مغادرة الصفحة.
انتقل إلى Developer → Webhooks وافتح علامة تبويب Activity لعرض أداء التسليم عبر نقاط النهاية الخاصة بك.يعرض Delivery activity المحاولات بمرور الوقت، مجمّعةً في Attempts per 5 minutes أو Attempts per hour أو Attempts per day وفقًا للإطار الزمني. ينقسم كل شريط حسب النتيجة، ويؤدي تمرير المؤشر فوق مقطع إلى عرض الحالة وعدد المحاولات ونسبته من الإجمالي. وفي نقطة النهاية، تلخص Delivery stats (last 24h) في علامة تبويب Overview المعلومات نفسها لليوم الماضي.
يوضح عمود Error rate (24h) في علامة تبويب Endpoints بسرعة نقاط النهاية التي تحتاج إلى اهتمام، قبل فتح أي منها.
هل أنت مستعد لنشر معالج webhook في بيئة الإنتاج؟ نوفر أدلة خاصة بالمنصات لمساعدتك على نشر webhooks لدى موفري الخدمات السحابية الشائعين، مع أفضل الممارسات لكل منصة.
Vercel
انشر webhooks على Vercel باستخدام serverless functions
Cloudflare Workers
شغّل webhooks على شبكة Cloudflare الطرفية
Supabase Edge Functions
ادمج webhooks مع Supabase
Netlify Functions
انشر webhooks كـ Netlify serverless functions
يتضمن كل دليل خاص بمنصة إعداد البيئة والتحقق من التوقيع وخطوات النشر الخاصة بموفر الخدمة.