Skip to main content
صورة غلاف Webhook
تقدم webhooks إشعارات في الوقت الفعلي عند وقوع أحداث في حسابك على Dodo Payments. استخدمها لأتمتة سير العمل، وتحديث قاعدة بياناتك، وإرسال الإشعارات، والحفاظ على مزامنة أنظمتك.
تتبع webhooks في Dodo Payments مواصفة Standard Webhooks للتحقق من التوقيعات وبنية الحمولة.

الميزات الرئيسية

توفر webhooks التسليم في الوقت الفعلي مع أمان مدمج، وعمليات إعادة محاولة تلقائية، وتصفية للأحداث. تتضمن جميع SDKs الرسمية أدوات مساعدة للتحقق من التوقيعات، كما توفر لوحة المعلومات أدوات للاختبار والمراقبة وإعادة التشغيل.

البدء

1

Go to Developer → Webhooks

في لوحة معلومات Dodo Payments، انتقل إلى Developer → Webhooks.
2

Click Add Endpoint

انقر على Add endpoint لإنشاء مستقبِل webhook جديد.
3

Enter Your Endpoint URL

أدخل عنوان HTTPS URL الذي سترسل إليه Dodo Payments أحداث webhook، أو اختر موصل تكامل (Slack أو Discord أو Zapier أو Resend أو غيرها) لتوجيه الأحداث إلى خدمة خارجية من دون كتابة تعليمات برمجية.
4

Select Events

اختر الأحداث التي تريد استلامها. تُنظَّم الأحداث حسب المورد (payment أو subscription أو dispute أو غيرها). يمكنك اختيار أحداث فردية أو مورد كامل لاستلام جميع الأحداث المرتبطة به.
5

Save

انقر على Create endpoint. سيظهر سر توقيع webhook في علامة التبويب Overview الخاصة بنقطة النهاية.
حافظ على أمان سر webhook. لا تكشفه مطلقًا في التعليمات البرمجية من جهة العميل أو في نظام التحكم بالإصدارات.
لتدوير سر webhook، افتح نقطة النهاية وانقر على Rotate secret بجوار السر في علامة التبويب Overview. يظل السر القديم صالحًا لمدة 24 ساعة بعد التدوير.

موصلات التكامل

وجّه أحداث webhook مباشرةً إلى خدمات خارجية باستخدام موصلات التكامل، مما يلغي الحاجة إلى إنشاء معالجات webhook مخصصة وصيانتها.

كيفية عمل الموصلات

يحوّل الموصل أحداث Dodo Payments إلى التنسيق الذي تتوقعه الوجهة. وتعتمد التفاصيل التي تقدمها على الوجهة: تعرض لوحة المعلومات جميع الموصلات المتاحة لنشاطك التجاري. راجع External Integrations لمعرفة ما يمكن لكل وجهة فعله بالأحداث.

إعداد موصل

عند إنشاء نقطة نهاية أو تعديلها، اختر موصلًا وستعرض اللوحة الجانبية تعليمات الإعداد الخاصة بالوجهة. اختبر التحويل قبل الحفظ للتأكد من تحويل الأحداث بشكل صحيح.
استخدم موصلًا للوصول إلى وجهة مدعومة من دون كتابة تعليمات برمجية. إذا كنت بحاجة إلى منطق مخصص، فاستخدم نقطة نهاية قياسية مع transformation بدلًا من ذلك.

تهيئة الأحداث المشترك بها

هيّئ الأحداث التي تستلمها كل نقطة نهاية webhook.
1

Navigate to Webhook Endpoints

انتقل إلى Developer → Webhooks وانقر على نقطة النهاية الخاصة بك.
2

Open Event Configuration

انقر على Edit لفتح اللوحة الجانبية لتهيئة نقطة النهاية.
3

Select Events

يعرض محدد نوع الحدث جميع أحداث webhook المتاحة في شجرة قابلة للبحث، مجمعة حسب المورد (مثل payment وsubscription وdispute). حدد مربعات الاختيار بجوار الأحداث التي تريد استلامها. يمكنك اختيار أحداث فردية أو مورد كامل أو المزج بينهما.
4

Save Configuration

انقر على Save لتطبيق تغييراتك.
إذا ألغيت تحديد جميع الأحداث، فستستلم نقطة نهاية webhook كل أنواع الأحداث. حدد الأحداث التي يحتاج إليها تطبيقك فقط.

كتالوج الأحداث

انتقل إلى Developer → Webhooks وافتح علامة التبويب Event catalog لرؤية كل نوع من الأحداث التي يمكن لـ Dodo Payments إرسالها. اختر حدثًا لعرض مخططه وحمولة نموذجية.

Webhook Events Guide

تصفح الأحداث كوثائق مرجعية، مجمعة حسب المورد.

تسليم Webhook

مهلات الانتظار

تحتوي Webhooks على مهلة 30 ثانية لكلٍّ من عمليات الاتصال والقراءة. عالج Webhooks بشكل غير متزامن عبر إرجاع رمز الحالة 200 فورًا، ثم عالج الحدث في الخلفية.

عمليات إعادة المحاولة التلقائية

تُعاد محاولة عمليات التسليم الفاشلة باستخدام تأخير أُسّي، بحد أقصى 8 محاولات إجمالًا: استخدم لوحة التحكم لإعادة تشغيل الرسائل الفاشلة يدويًا أو لاسترداد الرسائل دفعةً واحدة من نطاق زمني محدد.

Idempotency

تتضمن كل webhook رأس webhook-id فريدًا. خزّن هذا المعرّف لاكتشاف الأحداث المكررة وتخطيها، إذ قد تؤدي إعادة المحاولة إلى تسليم الحدث نفسه عدة مرات.
طبّق دائمًا عمليات التحقق من Idempotency. بسبب عمليات إعادة المحاولة، قد تتلقى الحدث نفسه عدة مرات.

ترتيب الأحداث

قد تصل الأحداث بترتيب غير صحيح بسبب عمليات إعادة المحاولة أو ظروف الشبكة. تتضمن كل 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.
قدّم سر webhook عبر DODO_PAYMENTS_WEBHOOK_KEY عند تهيئة عميل Dodo Payments.

التحقق اليدوي (بديل)

إذا لم تكن تستخدم SDK، فتحقق من التوقيع بنفسك:
  1. أنشئ المحتوى الموقّع بضم webhook-id وwebhook-timestamp ونص الطلب الخام باستخدام النقاط: {id}.{timestamp}.{body}. استخدم النص الخام تمامًا كما استلمته، قبل أي تحليل لـ JSON.
  2. خذ سر webhook. إذا بدأ بـ whsec_، فأزل تلك البادئة، ثم فك ترميز Base64 للجزء المتبقي للحصول على مفتاح التوقيع.
  3. احسب HMAC-SHA256 للمحتوى الموقّع باستخدام مفتاح التوقيع، ثم شفّر النتيجة بترميز Base64.
  4. يحتوي الرأس webhook-signature على توقيع واحد أو أكثر مفصولة بمسافات، وكل توقيع بالصيغة v1,<base64-signature>. يكون الطلب صالحًا إذا تطابق أي توقيع v1 مع توقيعك. قارن باستخدام دالة ذات وقت ثابت.
  5. ارفض الطلب إذا كان webhook-timestamp بعيدًا جدًا عن الوقت الحالي، لمنع هجمات إعادة التشغيل. تسمح مكتبات Standard Webhooks بخمس دقائق.
راجع مكتبات Standard Webhooks للاطلاع على تطبيقات مرجعية. للاطلاع على تنسيقات حمولات الأحداث، راجع Webhook Payload.

عناوين IP المصدر

يُعد التحقق من التوقيع طريقة المصادقة المدعومة. فهو يثبت أن الطلب وُقّع باستخدام سر webhook الخاص بك، وهو أمر لا يستطيع فحص مستوى الشبكة إثباته. تأتي عمليات تسليم Webhooks من مجموعة من عناوين IP التي تتغير بمرور الوقت. لا تعتمد على قوائم السماح لعناوين IP للمصادقة. تحقّق دائمًا من الرأس webhook-signature بدلًا من ذلك، كما هو موضح في التحقق من التوقيعات. إذا كان جدار الحماية يتطلب قائمة سماح:
  • لا تضع العناوين في التعليمات البرمجية بشكل دائم. تتغير النطاقات بمرور الوقت، وقد تحظر القواعد القديمة عمليات التسليم بصمت.
  • اطلب النطاقات الحالية من support@dodopayments.com قبل تقييد جدار الحماية.
  • راقب إشعارات التغيير. عند تغير عناوين التسليم، نُخطر التجار المتأثرين عبر البريد الإلكتروني — طبّق التحديثات قبل التاريخ المحدد.
  • أبقِ التحقق من التوقيع مفعّلًا بغض النظر عن أي قواعد شبكة تضيفها.
في منصات الاستضافة المُدارة وserverless، غالبًا ما يكون تصفية عناوين IP الواردة غير متاح أو غير عملي. يُعد التحقق من التوقيع الإجراء الصحيح في تلك البيئات.
تُعامل عملية التسليم المحظورة على أنها فشل، وتُعاد محاولتها وفق الجدول الموضح في عمليات إعادة المحاولة التلقائية. إذا تسببت قواعد جدار الحماية في فشل عمليات التسليم، يمكنك إعادة إرسالها بعد إصلاح القواعد — راجع إعادة تشغيل الرسائل واستردادها.

الاستجابة إلى Webhooks

يجب أن يعيد معالج webhook القيمة 2xx status code لتأكيد الاستلام. تُعامل أي استجابة أخرى على أنها فشل، وستُعاد محاولة webhook.

أفضل الممارسات

  • استخدم HTTPS فقط. تكون نقاط نهاية HTTP عرضة للاعتراض.
  • استجب فورًا. أعد رمز الحالة 200 على الفور، ثم عالج الحدث بشكل غير متزامن.
  • طبّق Idempotency. استخدم الرأس webhook-id لاكتشاف الأحداث المكررة وتخطيها.
  • أمّن سرك. خزّن DODO_PAYMENTS_WEBHOOK_KEY في متغيرات البيئة أو مدير أسرار، وليس في نظام التحكم بالإصدارات.

بنية حمولة Webhook

تنسيق الطلب

الرؤوس

string
مطلوب
معرّف فريد لحدث webhook هذا. استخدمه لعمليات التحقق من Idempotency.
string
مطلوب
توقيع HMAC SHA256 للتحقق من صحة webhook.
string
مطلوب
طابع زمني Unix (بالثواني) لوقت إرسال webhook.

نص الطلب

string
مطلوب
معرّف نشاطك التجاري في Dodo Payments.
string
مطلوب
نوع الحدث الذي أدى إلى تشغيل webhook هذا (مثل payment.succeeded وsubscription.active).
string
مطلوب
طابع زمني بتنسيق ISO 8601 لوقت وقوع الحدث.
object
مطلوب
حمولة خاصة بالحدث تتضمن معلومات تفصيلية عنه.

مثال على الحمولة

Event Types

تصفح جميع أنواع أحداث webhook المتاحة

Event Payloads

اعرض مخططات الحمولات التفصيلية لكل حدث

Handle Payment Failures

استجب إلى payment.failed واسترد المدفوعات المرفوضة

اختبار Webhooks

إرسال حدث نموذجي

اختبر تكامل webhook مباشرةً من لوحة التحكم:
1

Navigate to Webhooks

انتقل إلى Developer → Webhooks وانقر على نقطة النهاية الخاصة بك.
2

Open Testing Tab

انقر على علامة التبويب Testing.
3

Send Example

حدّد نوع حدث وانقر على Send example. تُسلّم الحمولة النموذجية إلى عنوان URL لنقطة النهاية تمامًا مثل الحدث الحقيقي، وبالتوقيع نفسه.
4

Check Your Endpoint

تأكد من وصول الحدث، ومن نجاح التحقق من توقيعك، ومن إرجاعك رمز الحالة 2xx.
تُعاد محاولة الرسائل الفاشلة المُرسلة من علامة التبويب Testing وفق جدول إعادة المحاولة المعتاد، مثل أي webhook آخر.

مثال على التنفيذ

تطبيق Express.js كامل مع التحقق من webhook ومعالجته:
اختبر معالج webhook بشكل شامل باستخدام واجهة الاختبار في لوحة التحكم قبل معالجة أحداث الإنتاج. يساعد ذلك في تحديد المشكلات وإصلاحها مبكرًا.

اختبار Webhooks باستخدام CLI

يحتوي Dodo Payments CLI على أمرين لاختبار Webhooks أثناء التطوير المحلي.

الاستماع إلى Webhooks المباشرة محليًا

أعد توجيه أحداث webhook الحقيقية من حساب وضع الاختبار إلى خادم التطوير المحلي:
يفتح CLI اتصال WebSocket ويعيد توجيه كل حدث webhook إلى نقطة النهاية المحلية (مثل http://localhost:3000/webhook)، مع الحفاظ على جميع الرؤوس لاختبار التحقق من التوقيع.
يعمل المستمع مع مفاتيح API الخاصة بوضع الاختبار فقط. شغّل dodo login وحدد Test Mode أولًا.

تشغيل أحداث Webhook وهمية

أرسل حمولات webhook وهمية إلى أي نقطة نهاية دون إنشاء معاملات حقيقية:
تتيح لك هذه الأداة التفاعلية اختيار نوع حدث وإرسال حمولة وهمية واقعية إلى نقطة النهاية الخاصة بك. وتعمل في حلقة كي تتمكن من اختبار أحداث متعددة في جلسة واحدة. يغطي أمر التشغيل عائلات الاشتراكات والمدفوعات والمبالغ المستردة والنزاعات ومفاتيح الترخيص والمدفوعات للتجار والائتمانات وعمليات الدفع المتروكة والتحصيل والمنح الخاصة بالاستحقاقات. ولا يرسل subscription.past_due أو subscription.unpaused. راجع Supported Webhook Events للقائمة الدقيقة.
حمولات webhook الوهمية من dodo wh trigger غير موقّعة. استخدم طريقة التحليل غير المتحقق (unsafeUnwrap في TypeScript، وunsafe_unwrap في Python، وUnsafeUnwrap في Go) في معالج webhook أثناء الاختبار فقط.

CLI Webhook Testing Docs

راجع وثائق اختبار webhook الكاملة الخاصة بـ CLI

الإعدادات المتقدمة

توفر علامة التبويب Advanced خيارات إعداد إضافية لضبط سلوك نقطة نهاية webhook بدقة.

تحديد معدل الطلبات (Throttling)

تحكم في معدل تسليم أحداث webhook إلى نقطة النهاية الخاصة بك. لا يُطبّق حد للمعدل على Webhooks افتراضيًا، ويتم تسليم الأحداث فور حدوثها.
1

Open Advanced Tab

من صفحة تفاصيل نقطة النهاية، انقر على علامة التبويب Advanced.
2

Configure Rate Limit

وسّع قسم Endpoint throttling.
3

Set Your Limit

أدخل الحد الأقصى لعدد الرسائل في الثانية، ثم انقر على Save. تُوضع عمليات التسليم التي تتجاوز هذا المعدل في قائمة انتظار بدلًا من إسقاطها.

الرؤوس المخصصة

أضف رؤوس HTTP مخصصة إلى جميع طلبات webhook المُرسلة إلى نقطة النهاية. يفيد ذلك في المصادقة أو التوجيه أو إضافة البيانات الوصفية.
1

Add Headers

في قسم Custom headers، أدخل اسم الرأس وقيمته.
2

Add Multiple Headers

انقر على Add header لكل رأس إضافي، ثم انقر على Save.

التحويلات

تتيح لك التحويلات تعديل حمولة webhook وإعادة توجيهها اختياريًا إلى عنوان URL مختلف. استخدم التحويلات من أجل:
  • تعديل بنية الحمولة قبل المعالجة
  • توجيه Webhooks إلى نقاط نهاية مختلفة استنادًا إلى المحتوى
  • إضافة الحقول إلى الحمولة أو إزالتها منها
  • تحويل تنسيقات البيانات
1

Enable Transformations

في قسم Transformation، فعّل Enable transformation.
2

Configure Transformation

اكتب قواعد التحويل بلغة JavaScript في محرر التعليمات البرمجية، ثم انقر على Save. يجب أن يعيد الكود كائن webhook من handler().
3

Test Transformation

استخدم واجهة اختبار التحويل للتحقق من عمل التحويل بشكل صحيح قبل تشغيله.
يمكن أن تؤثر التحويلات في أداء تسليم Webhooks. اختبرها بدقة، واجعل منطق التحويل بسيطًا وفعّالًا.

مراقبة سجلات Webhooks

توفر علامة التبويب Logs إمكانية الاطلاع على حالة تسليم 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

انقر على أي رسالة لفتح صفحة تفاصيلها، التي تعرض:
  • حمولة webhook الكاملة
  • كل محاولة تسليم مع رمز الاستجابة والمدة
  • الطابع الزمني لكل محاولة
  • أي رسائل خطأ من نقطة النهاية الخاصة بك
تتضمن كل محاولة إجراء Replay لإعادة دفع تلك الرسالة دون مغادرة الصفحة.

مراقبة النشاط

انتقل إلى Developer → Webhooks وافتح علامة التبويب Activity للاطلاع على أداء التسليم عبر نقاط النهاية الخاصة بك. يعرض نشاط التسليم المحاولات بمرور الوقت، مجمّعةً على شكل Attempts per 5 minutes أو Attempts per hour أو Attempts per day حسب النافذة. يُقسّم كل شريط حسب النتيجة، ويؤدي تمرير المؤشر فوق مقطع إلى عرض الحالة وعدد المحاولات ونسبته من الإجمالي. في نقطة النهاية، تلخّص Delivery stats (last 24h) في علامة التبويب Overview المعلومات نفسها لليوم السابق.
يعرض عمود Error rate (24h) في علامة التبويب Endpoints نقاط النهاية التي تحتاج إلى عناية بنظرة سريعة.

إعادة تشغيل الرسائل واستردادها

تعتمد طريقة إعادة دفع الرسالة على عدد الرسائل التي تحتاج إليها:
  • رسالة واحدة — افتحها من علامة التبويب Logs واستخدم إجراء Replay في المحاولة.
  • نطاق من الرسائل — افتح نقطة النهاية، إذ تعمل أوضاع المعالجة المجمعة على نقطة نهاية واحدة في كل مرة.

إعادة التشغيل دفعةً واحدة

افتح نقطة النهاية من Developer → Webhooks. تتوفر ثلاثة أوضاع، ويعمل كل منها على نقطة النهاية وحدها:
1

Open More Actions

في نقطة النهاية، افتح More actions واختر أحد الأوضاع الثلاثة السابقة.
2

Set the Range

أدخل النطاق الذي يطلبه الوضع، كما هو موضح في الجدول.
3

Start the Run

انقر على Recover أو Replay، حسب الوضع الذي اخترته.
يظهر كل تشغيل ضمن Replay history في علامة التبويب Overview لنقطة النهاية، مع وضعه ونطاقه الزمني وحالته وعدد الرسائل المُعاد إرسالها.

تنبيهات البريد الإلكتروني

لا توفر لوحة تحكم Webhooks تنبيهات عبر البريد الإلكتروني لعمليات التسليم الفاشلة. لمراقبة عمليات التسليم، انتقل إلى Developer → Webhooks وتحقق من علامتي التبويب Logs وActivity.

النشر على المنصات السحابية

أدلة خاصة بالمنصة لنشر معالجات webhook على موفري الخدمات السحابية الشائعين:

Vercel

انشر Webhooks على Vercel باستخدام serverless functions

Cloudflare Workers

شغّل Webhooks على شبكة edge الخاصة بـ Cloudflare

Supabase Edge Functions

ادمج Webhooks مع Supabase

Netlify Functions

انشر Webhooks كـ Netlify serverless functions

مرجع API ذي صلة

Create Webhook

أنشئ نقاط نهاية webhook واضبطها برمجيًا

List Webhooks

استرد نقاط نهاية webhook وأدرها
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦