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

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

Real-time Delivery

تلقَّ إشعارات فورية عند وقوع الأحداث

Secure by Default

يتضمن التحقق من التوقيع باستخدام HMAC SHA256

Automatic Retries

منطق إعادة محاولة مضمّن مع تأخير أُسّي

Event Filtering

اشترك فقط في الأحداث التي تحتاج إليها

البدء

1

Access Webhook Settings

انتقل إلى لوحة تحكم DodoPayments، ثم انتقل إلى Developer > Webhooks.
2

Create Webhook Endpoint

انقر على Add Webhook لإنشاء نقطة نهاية Webhook جديدة.
إضافة Webhook
3

Add Endpoint URL

أدخل عنوان URL الذي تريد تلقي أحداث Webhook عليه.
4

Select Events to Receive

اختر الأحداث المحددة التي يجب أن تستمع إليها نقطة نهاية Webhook، وذلك بتحديدها من قائمة الأحداث.
ستؤدي الأحداث المحددة فقط إلى تشغيل Webhooks لنقطة النهاية لديك، مما يساعدك على تجنب حركة المرور والمعالجة غير الضروريتين.
5

Get Secret Key

احصل على Secret Key الخاص بـ Webhook من صفحة الإعدادات. ستستخدمه للتحقق من صحة Webhooks المستلمة.
حافظ على أمان مفتاح Webhook السري، ولا تكشفه مطلقًا في التعليمات البرمجية من جانب العميل أو في المستودعات العامة.
6

Rotate Secret (Optional)

عند الحاجة، يمكنك تدوير السر الخاص بـ Webhook لتعزيز الأمان. انقر على زر Rotate Secret في إعدادات Webhook.
سيؤدي تدوير السر إلى انتهاء صلاحيته واستبداله بسر جديد. سيظل السر القديم صالحًا خلال الساعات الأربع والعشرين التالية فقط. بعد ذلك، سيفشل التحقق باستخدام السر القديم.
استخدم تدوير السر دوريًا أو فورًا إذا شككت في اختراق السر الحالي.

تكوين الأحداث المشترك فيها

يمكنك تكوين الأحداث المحددة التي تريد تلقيها لكل نقطة نهاية Webhook.

الوصول إلى تكوين الأحداث

1

Navigate to Webhook Details

انتقل إلى لوحة تحكم Dodo Payments وانتقل إلى Developer > Webhooks.
2

Select Your Endpoint

انقر على نقطة نهاية Webhook التي تريد تكوينها.
3

Open Event Settings

في صفحة تفاصيل Webhook، سترى قسم “Subscribed events”. انقر على زر Edit لتعديل اشتراكات الأحداث.

إدارة اشتراكات الأحداث

1

View Available Events

تعرض الواجهة جميع أحداث Webhook المتاحة في بنية هرمية. تُجمّع الأحداث حسب الفئة (مثل dispute وpayment وsubscription).
2

Search and Filter

استخدم شريط البحث للعثور بسرعة على أحداث محددة من خلال كتابة أسماء الأحداث أو الكلمات المفتاحية.
3

Select Events

حدد مربعات الاختيار بجانب الأحداث التي تريد تلقيها. يمكنك:
  • تحديد الأحداث الفرعية الفردية (مثل dispute.accepted وdispute.challenged)
  • تحديد الأحداث الأصلية لتلقي جميع الأحداث الفرعية المرتبطة بها
  • الجمع بين أحداث محددة وفقًا لاحتياجاتك
4

Review Event Details

مرّر مؤشر الماوس فوق رمز المعلومات (ⓘ) بجانب كل حدث لعرض وصف يوضح وقت تشغيل ذلك الحدث.
5

Save Configuration

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

تسليم Webhook

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

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

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

إذا فشل تسليم Webhook، تعيد Dodo Payments المحاولة تلقائيًا باستخدام تأخير أُسّي لتجنب إغراق نظامك.
الحد الأقصى هو 8 محاولات إعادة لكل حدث Webhook. على سبيل المثال، إذا فشل Webhook ثلاث مرات قبل نجاحه، فسيكون إجمالي وقت التسليم نحو 35 دقيقة و5 ثوانٍ بدءًا من المحاولة الأولى.
استخدم لوحة تحكم Dodo Payments لإعادة محاولة الرسائل الفردية يدويًا أو استرداد جميع الرسائل الفاشلة دفعةً واحدة في أي وقت.

Idempotency

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

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

قد تصل أحداث Webhook بترتيب غير صحيح بسبب عمليات إعادة المحاولة أو ظروف الشبكة. صمّم نظامك للتعامل مع الأحداث بأي تسلسل.
ستتلقى أحدث payload وقت التسليم، بغض النظر عن وقت إصدار حدث Webhook في الأصل.

تأمين Webhooks

لضمان أمان Webhooks، تحقّق دائمًا من payloads واستخدم HTTPS.

التحقق من التوقيعات

يتضمن كل طلب Webhook ترويسة webhook-signature، وهي توقيع HMAC SHA256 لـ payload الخاص بـ Webhook والطابع الزمني، وموقعة باستخدام مفتاحك السري.

التحقق باستخدام SDK (موصى به)

تتضمن جميع SDKs الرسمية أدوات مساعدة مضمّنة للتحقق من Webhooks الواردة وتحليلها بأمان. تتوفر طريقتان:
  • unwrap(): للتحقق من التوقيعات باستخدام مفتاح Webhook السري
  • unsafe_unwrap(): لتحليل payloads دون التحقق
مرّر سر Webhook الخاص بك عبر DODO_PAYMENTS_WEBHOOK_KEY عند تهيئة عميل Dodo Payments.

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

إذا لم تكن تستخدم SDK، يمكنك التحقق من التوقيعات بنفسك باتباع مواصفة Standard Webhooks:
  1. أنشئ الرسالة الموقعة عن طريق دمج webhook-id وwebhook-timestamp وسلسلة payload الخام المحوّلة إلى نص كما هي، مع الفصل بينها بنقاط (.).
  2. احسب HMAC SHA256 لهذه السلسلة باستخدام مفتاح Webhook السري من لوحة التحكم.
  3. قارن التوقيع المحسوب بترويسة webhook-signature. إذا تطابقا، يكون Webhook أصليًا.
نتبع مواصفة Standard Webhooks. يمكنك استخدام مكتباتهم للتحقق من التوقيعات: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. لمعرفة تنسيقات payload الخاصة بالأحداث، راجع Webhook Payload.

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

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

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

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

بنية Payload الخاص بـ Webhook

يساعدك فهم بنية payload الخاص بـ Webhook على تحليل الأحداث ومعالجتها بشكل صحيح.

تنسيق الطلب

الترويسات

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

نص الطلب

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

مثال على Payload

Event Types

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

Event Payloads

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

Handle Payment Failures

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

اختبار Webhooks

يمكنك اختبار تكامل Webhook مباشرةً من لوحة تحكم Dodo Payments للتأكد من عمل نقطة النهاية بشكل صحيح قبل إطلاقها.
تفاصيل نقطة النهاية

الوصول إلى واجهة الاختبار

1

Navigate to Webhooks

انتقل إلى لوحة تحكم Dodo Payments وانتقل إلى Developer > Webhooks.
2

Select Your Endpoint

انقر على نقطة نهاية Webhook للوصول إلى صفحة تفاصيلها.
3

Open Testing Tab

انقر على علامة التبويب Testing للوصول إلى واجهة اختبار Webhook.

اختبار Webhook الخاص بك

توفر واجهة الاختبار طريقة شاملة لاختبار نقطة نهاية Webhook:
1

Select Event Type

استخدم القائمة المنسدلة لتحديد نوع الحدث المحدد الذي تريد اختباره (مثل payment.succeeded وpayment.failed وغيرهما).
تحتوي القائمة المنسدلة على جميع أنواع أحداث Webhook المتاحة التي يمكن لنقطة النهاية استقبالها.
2

Review Schema and Example

تعرض الواجهة كلًا من Schema (بنية البيانات) وExample (payload نموذجي) لنوع الحدث المحدد.
3

Send Test Event

انقر على زر Send Example لإرسال Webhook اختباري إلى نقطة النهاية لديك.
مهم: لن تتم إعادة محاولة الرسائل الفاشلة المرسلة عبر واجهة الاختبار. هذا مخصص للاختبار فقط.

التحقق من الاختبار

1

Check Your Endpoint

راقب سجلات نقطة نهاية Webhook للتأكد من استلام حدث الاختبار.
2

Verify Signature

تأكد من أن التحقق من التوقيع يعمل بشكل صحيح مع payload الاختبار.
3

Test Response

تأكد من أن نقطة النهاية تعيد رمز الحالة 2xx لتأكيد الاستلام.

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

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

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

يوفر Dodo Payments CLI أمرين لاختبار Webhooks أثناء التطوير المحلي، دون الحاجة إلى مغادرة الطرفية.

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

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

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

أرسل payloads وهمية لـ Webhook إلى أي نقطة نهاية دون إنشاء معاملات حقيقية:
تتيح لك هذه الأداة التفاعلية الاختيار من جميع أنواع الأحداث المدعومة، وترسل payloads وهمية واقعية إلى نقطة النهاية لديك. وتعمل في حلقة كي تتمكن من اختبار أحداث متعددة في جلسة واحدة.
لا تحمل payloads Webhook الوهمية من dodo wh trigger توقيعًا. استخدم unsafe_unwrap() بدلًا من unwrap() في معالج Webhook أثناء الاختبار فقط.

CLI Webhook Testing Docs

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

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

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

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

تحكم في معدل تسليم أحداث Webhook إلى نقطة النهاية لديك لمنع إغراق نظامك.
1

Access Rate Limit Settings

في علامة التبويب Advanced، حدد قسم “Rate Limit (throttling)”.
2

Configure Rate Limit

انقر على زر Edit لتعديل إعدادات حد المعدل.
تُطبّق Webhooks افتراضيًا مع “No rate limit”، ما يعني تسليم الأحداث فور وقوعها.
3

Set Limits

كوّن حد المعدل المطلوب للتحكم في وتيرة تسليم Webhook ومنع زيادة حمل النظام.
استخدم تحديد معدل الطلبات عندما يحتاج معالج Webhook إلى وقت لمعالجة الأحداث أو عندما تريد تجميع عدة أحداث معًا.

الترويسات المخصصة

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

Add Custom Header

في قسم “Custom Headers”، أدخل Key وValue للترويسة المخصصة.
2

Add Multiple Headers

انقر على زر + لإضافة ترويسات مخصصة إضافية حسب الحاجة.
3

Save Configuration

ستُدرج ترويساتك المخصصة في جميع طلبات Webhook المرسلة إلى نقطة النهاية هذه.

التحويلات

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

Enable Transformations

بدّل مفتاح Enabled إلى وضع التشغيل لتفعيل ميزة التحويل.
2

Configure Transformation

انقر على Edit transformation لتعريف قواعد التحويل.
يمكنك استخدام JavaScript لتحويل payload الخاص بـ Webhook وتحديد عنوان URL مستهدف مختلف.
3

Test Transformation

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

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

توفر علامة تبويب Logs رؤية شاملة لحالة تسليم Webhook، مما يتيح لك مراقبة أحداث Webhook وتصحيح أخطائها وإدارتها بفعالية.
السجلات

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

توفر علامة تبويب Activity رؤى فورية حول أداء تسليم Webhook من خلال التحليلات المرئية.
النشاط

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

ابقَ على اطلاع بصحة Webhook لديك من خلال إشعارات البريد الإلكتروني التلقائية. عندما يبدأ تسليم Webhook بالفشل أو تتوقف نقطة النهاية عن الاستجابة، ستتلقى تنبيهات عبر البريد الإلكتروني لتتمكن من معالجة المشكلات بسرعة والحفاظ على تشغيل تكاملاتك بسلاسة.
إعدادات تنبيهات Webhook التي تعرض تكوين إشعارات البريد الإلكتروني

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

1

Navigate to Alerting Settings

انتقل إلى لوحة تحكم Dodo Payments وانتقل إلى Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

فعّل Email notifications لبدء تلقي التنبيهات حول مشكلات تسليم Webhook.
3

Configure Email Address

أدخل عنوان البريد الإلكتروني الذي تريد تلقي تنبيهات Webhook عليه. سنرسل إشعارات إلى هذا العنوان عند وقوع أحداث معينة في إعداد Webhooks لديك، مثل مشكلات التسليم التي قد تؤثر في تكاملاتك.
فعّل التنبيهات عبر البريد الإلكتروني لاكتشاف مشكلات تسليم Webhook مبكرًا والحفاظ على تكاملات موثوقة. ستتلقى إشعارًا عند فشل عمليات التسليم أو عدم استجابة نقطة النهاية.

النشر على الأنظمة السحابية

هل أنت مستعد لنشر معالج Webhook في بيئة الإنتاج؟ نوفر أدلة خاصة بكل منصة لمساعدتك على نشر Webhooks لدى موفري الخدمات السحابية المشهورين، مع أفضل الممارسات لكل منصة.

Vercel

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

Cloudflare Workers

شغّل Webhooks على شبكة Cloudflare الطرفية

Supabase Edge Functions

ادمج Webhooks مع Supabase

Netlify Functions

انشر Webhooks كدوال serverless على Netlify
يتضمن كل دليل خاص بمنصة إعداد البيئة، والتحقق من التوقيع، وخطوات النشر الخاصة بموفر الخدمة المعني.

مرجع API ذي صلة

Create Webhook

مرجع API لإنشاء نقاط نهاية Webhook وتكوينها برمجيًا

List Webhooks

مرجع API لاسترداد نقاط نهاية Webhook وإدارتها
آخر تعديل في ٣١ يوليو ٢٠٢٦