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

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

تسليم في الوقت الحقيقي

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

آمن بشكل افتراضي

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

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

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

تصفية الأحداث

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

البدء

1

الوصول إلى إعدادات Webhook

انتقل إلى لوحة معلومات DodoPayments وانتقل إلى Settings > Webhooks.
2

إنشاء نقطة نهاية Webhook

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

إضافة عنوان URL لنقطة النهاية

أدخل عنوان URL حيث تريد استلام أحداث Webhook.
4

اختيار الأحداث التي تريد استلامها

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

الحصول على مفتاح سري

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

تدوير السر (اختياري)

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

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

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

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

1

انتقل إلى تفاصيل Webhook

انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى Settings > Webhooks.
2

اختر نقطة النهاية الخاصة بك

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

فتح إعدادات الأحداث

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

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

1

عرض الأحداث المتاحة

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

البحث والتصفية

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

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

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

مراجعة تفاصيل الحدث

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

حفظ التكوين

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

تسليم Webhook

المهلات

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

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

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

عدم التكرار

يتضمن كل حدث Webhook رأسًا فريدًا 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 بترتيب غير صحيح بسبب إعادة المحاولات أو ظروف الشبكة. صمم نظامك للتعامل مع الأحداث بأي تسلسل.
ستتلقى آخر حمولة في وقت التسليم، بغض النظر عن موعد إصدار حدث Webhook في الأصل.

تأمين Webhooks

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

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

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

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

تتضمن جميع SDK الرسمية مساعدات مدمجة للتحقق من صحة Webhooks الواردة وتحليلها بشكل آمن. تتوفر طريقتان:
  • unwrap(): يتحقق من التوقيعات باستخدام مفتاح Webhook السري الخاص بك
  • unsafe_unwrap(): يحلل الحمولة دون التحقق
قدم مفتاح Webhook السري الخاص بك عبر DODO_PAYMENTS_WEBHOOK_KEY عند تهيئة عميل مدفوعات Dodo.
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 لتلك السلسلة باستخدام مفتاح Webhook السري الخاص بك من لوحة المعلومات.
  3. قارن التوقيع المحسوب مع رأس webhook-signature. إذا تطابقت، فإن Webhook أصلي.
نتبع مواصفات Webhooks القياسية. يمكنك استخدام مكتباتهم للتحقق من التوقيعات: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. لمخططات تنسيق الحمولة الخاصة بالأحداث، راجع حمولة Webhook.

الرد على Webhooks

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

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

استخدم دائمًا عناوين URL HTTPS لنقاط نهاية Webhook. نقاط نهاية HTTP عرضة لهجمات الرجل في المنتصف وتعرض بيانات Webhook الخاصة بك.
أعد رمز الحالة 200 على الفور عند استلام Webhook. قم بمعالجة الحدث بشكل غير متزامن لتجنب المهلات.
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

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

تنسيق الطلب

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

الرؤوس

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

جسم الطلب

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

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

{
  "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

انتقل إلى Webhooks

انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى Settings > Webhooks.
2

اختر نقطة النهاية الخاصة بك

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

فتح علامة التبويب للاختبار

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

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

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

اختيار نوع الحدث

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

مراجعة المخطط والمثال

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

إرسال حدث اختبار

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

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

1

تحقق من نقطة النهاية الخاصة بك

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

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

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

اختبار الاستجابة

تأكد من أن نقطة النهاية الخاصة بك تعيد رمز الحالة 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.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
اختبر معالج Webhook الخاص بك بدقة باستخدام واجهة اختبار لوحة المعلومات قبل معالجة أحداث الإنتاج. يساعد ذلك في تحديد المشكلات وإصلاحها مبكرًا.

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

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

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

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

الوصول إلى إعدادات تحديد المعدل

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

تكوين تحديد المعدل

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

تعيين الحدود

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

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

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

إضافة رأس مخصص

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

إضافة رؤوس متعددة

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

حفظ التكوين

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

التحويلات

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

تفعيل التحويلات

قم بتبديل مفتاح مفعل لتفعيل ميزة التحويل.
2

تكوين التحويل

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

اختبار التحويل

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

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

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

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

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

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

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

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

1

انتقل إلى إعدادات التنبيه

انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى لوحة المعلومات → Webhooks → التنبيه.
2

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

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

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

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

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

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