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

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

Real-time Delivery

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

Secure by Default

تم تضمين التحقق من توقيع HMAC SHA256

Automatic Retries

منطق إعادة محاولة مدمج مع تراجع أسي

Event Filtering

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

البدء

1

Access Webhook Settings

انتقل إلى لوحة تحكم DodoPayments واذهب إلى Settings > Webhooks.
2

Create Webhook Endpoint

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

Add Endpoint URL

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

Select Events to Receive

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

Get Secret Key

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

Rotate Secret (Optional)

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

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

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

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

1

Navigate to Webhook Details

انتقل إلى لوحة تحكم Dodo Payments الخاصة بك واذهب إلى Settings > Webhooks.
2

Select Your Endpoint

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

Open Event Settings

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

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

1

View Available Events

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

Search and Filter

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

Select Events

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

Review Event Details

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

Save Configuration

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

تسليم Webhook

المهلات

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

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

إذا فشلت عملية تسليم Webhook، فإن مدفوعات Dodo تعيد المحاولة تلقائيًا مع التراجع الأسي لمنع إرهاق نظامك.
المحاولةالتأخيرالوصف
1على الفورتحدث المحاولة الأولى على الفور
25 ثوانٍالمحاولة الثانية بعد تأخير قصير
35 دقائقالمحاولة الثالثة مع زيادة التراجع
430 دقيقةالمحاولة الرابعة مع استمرار التراجع
5ساعتانالمحاولة الخامسة مع تأخير ممتد
65 ساعاتالمحاولة السادسة مع تأخير أطول
710 ساعاتالمحاولة السابعة مع أقصى تأخير
810 ساعاتالمحاولة النهائية - يتم وضع علامة على Webhook على أنه فشل إذا لم تنجح
بحد أقصى 8 محاولات إعادة لكل حدث ويب هوك. على سبيل المثال، إذا فشل ويب هوك ثلاث مرات قبل النجاح، فإن إجمالي وقت التسليم يكون حوالي 35 دقيقة و5 ثوانٍ من المحاولة الأولى.
استخدم لوحة تحكم Dodo Payments لإعادة محاولة الرسائل الفردية يدويًا أو لاستعادة جميع الرسائل الفاشلة دفعة واحدة في أي وقت.

عدم التكرار

كل حدث ويب هوك يتضمن رأسًا فريدًا webhook-id. استخدم هذا المعرف لتنفيذ عدم التكرار ومنع المعالجة المكررة.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
قم دائمًا بتنفيذ فحوصات عدم التكرار. نظرًا لوجود إعادة محاولات، قد تتلقى نفس الحدث عدة مرات.

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

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

تأمين Webhooks

لضمان أمان Webhooks الخاصة بك، تحقق دائمًا من الحمولة واستخدم HTTPS.

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

كل طلب ويب هوك يتضمن رأسًا webhook-signature؛ هو توقيع HMAC SHA256 لحمولة الويب هوك والطابع الزمني، موقّع بمفتاحك السري.

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

تتضمن جميع SDK الرسمية مساعدات مدمجة للتحقق من صحة Webhooks الواردة وتحليلها بشكل آمن. تتوفر طريقتان:
  • unwrap(): يتحقق من التواقيع باستخدام مفتاح سر الويب هوك الخاص بك
  • unsafe_unwrap(): يفسر الحمولات دون التحقق
قدم سر الويب هوك الخاص بك عبر DODO_PAYMENTS_WEBHOOK_KEY عند تهيئة عميل Dodo Payments.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

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

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

الرد على Webhooks

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

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

استخدم دائمًا عناوين URL عبر HTTPS لنقاط نهاية الويب هوك. عناوين HTTP عرضة لهجمات الوسيط وتعرض بيانات الويب هوك.
أعد رمز الحالة 200 فور استقبال الويب هوك. قم بمعالجة الحدث بشكل غير متزامن لتجنب نفاد الوقت.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
نفذ عدم التكرار باستخدام رأس webhook-id لمعالجة نفس الحدث عدة مرات بأمان دون تأثيرات جانبية.
خزّن سر الويب هوك بشكل آمن باستخدام متغيرات البيئة أو مدير الأسرار. لا تقم أبدًا بحفظ الأسرار في نظام التحكم بالإصدارات.

هيكل حمولة Webhook

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

تنسيق الطلب

POST /your-webhook-url
Content-Type: application/json

الرؤوس

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

جسم الطلب

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

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

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

اختبار Webhooks

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

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

1

Navigate to Webhooks

انتقل إلى لوحة تحكم Dodo Payments الخاصة بك واذهب إلى Settings > Webhooks.
2

Select Your Endpoint

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

Open Testing Tab

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

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

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

Select Event Type

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

Review Schema and Example

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

Send Test Event

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

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

1

Check Your Endpoint

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

Verify Signature

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

Test Response

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

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

إليك تنفيذ كامل باستخدام Express.js يظهر التحقق من Webhook ومعالجته:
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
app.use(express.json());

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
اختبر معالج الويب هوك الخاص بك بدقة باستخدام واجهة الاختبار في لوحة التحكم قبل معالجة الأحداث في الإنتاج. يساعد ذلك على تحديد وإصلاح المشكلات مبكرًا.

اختبار الويب هوكات باستخدام واجهة سطر الأوامر

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

الاستماع إلى الويب هوكات الحية محليًا

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

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

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

CLI Webhook Testing Docs

راجع توثيق اختبار الويب هوك الكامل في CLI

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

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

تحديد معدل (التحكم في التدفق)

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

Access Rate Limit Settings

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

Configure Rate Limit

انقر على زر Edit لتعديل إعدادات تحديد المعدل.
بشكل افتراضي، يتم تطبيق “بدون حد للمعدل” على الويب هوكات، مما يعني أن الأحداث تُسلم بمجرد حدوثها.
3

Set Limits

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

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

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

Add Custom Header

في قسم “الرؤوس المخصصة”، أدخل المفتاح والقيمة للرأس المخصص.
2

Add Multiple Headers

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

Save Configuration

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

التحويلات

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

Enable Transformations

قم بتبديل مفتاح Enabled لتنشيط ميزة التحويل.
2

Configure Transformation

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

Test Transformation

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

مراقبة سجلات الويب هوك

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

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

توفر علامة التبويب النشاط رؤى في الوقت الفعلي حول أداء تسليم الويب هوك مع تحليلات مرئية.
النشاط

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

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

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

1

Navigate to Alerting Settings

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

Enable Email Notifications

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

Configure Email Address

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

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

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