توفر Webhooks إشعارات في الوقت الحقيقي عند حدوث أحداث معينة في حساب مدفوعات Dodo الخاص بك. استخدم Webhooks لأتمتة سير العمل، وتحديث قاعدة البيانات الخاصة بك، وإرسال الإشعارات، والحفاظ على تزامن أنظمتك.
تتبع تنفيذ Webhook لدينا مواصفات Standard Webhooks ، مما يضمن التوافق مع أفضل الممارسات في الصناعة ومكتبات Webhook الموجودة.
الميزات الرئيسية
تسليم في الوقت الحقيقي استقبل إشعارات فورية عند حدوث الأحداث
آمن بشكل افتراضي تضمين التحقق من توقيع HMAC SHA256
إعادة المحاولة التلقائية منطق إعادة المحاولة المدمج مع التراجع الأسي
تصفية الأحداث اشترك فقط في الأحداث التي تحتاجها
البدء
الوصول إلى إعدادات Webhook
انتقل إلى لوحة معلومات DodoPayments وانتقل إلى Settings > Webhooks.
إنشاء نقطة نهاية Webhook
انقر على Add Webhook لإنشاء نقطة نهاية Webhook جديدة.
إضافة عنوان URL لنقطة النهاية
أدخل عنوان URL حيث تريد استلام أحداث Webhook.
اختيار الأحداث التي تريد استلامها
اختر الأحداث المحددة التي يجب أن تستمع إليها نقطة نهاية Webhook الخاصة بك عن طريق تحديدها من قائمة الأحداث. ستؤدي الأحداث المحددة فقط إلى تشغيل Webhooks إلى نقطة النهاية الخاصة بك، مما يساعدك على تجنب حركة المرور والمعالجة غير الضرورية.
الحصول على مفتاح سري
احصل على Secret Key من صفحة الإعدادات. ستستخدم هذا للتحقق من صحة Webhooks المستلمة. احتفظ بمفتاح Webhook السري الخاص بك آمنًا ولا تكشف عنه في التعليمات البرمجية على جانب العميل أو المستودعات العامة.
تدوير السر (اختياري)
إذا لزم الأمر، يمكنك تدوير مفتاح Webhook السري الخاص بك لتعزيز الأمان. انقر على زر تدوير السر في إعدادات Webhook الخاصة بك. سيؤدي تدوير السر إلى إنهائه واستبداله بواحد جديد. سيكون السر القديم صالحًا فقط لمدة 24 ساعة القادمة. بعد ذلك، ستفشل محاولة التحقق باستخدام السر القديم.
استخدم تدوير السر بشكل دوري أو على الفور إذا كنت تشك في أن سرك الحالي قد تم اختراقه.
تكوين الأحداث المشترك فيها
يمكنك تكوين الأحداث المحددة التي تريد استلامها لكل نقطة نهاية Webhook.
الوصول إلى تكوين الأحداث
انتقل إلى تفاصيل Webhook
انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى Settings > Webhooks.
اختر نقطة النهاية الخاصة بك
انقر على نقطة نهاية Webhook التي تريد تكوينها.
فتح إعدادات الأحداث
في صفحة تفاصيل Webhook، سترى قسم “الأحداث المشترك فيها”. انقر على زر تعديل لتعديل اشتراكات الأحداث الخاصة بك.
إدارة اشتراكات الأحداث
عرض الأحداث المتاحة
تعرض الواجهة جميع أحداث Webhook المتاحة منظمة في هيكل هرمي. يتم تجميع الأحداث حسب الفئة (مثل dispute، payment، subscription).
البحث والتصفية
استخدم شريط البحث للعثور بسرعة على أحداث معينة عن طريق كتابة أسماء الأحداث أو الكلمات الرئيسية.
اختيار الأحداث
تحقق من المربعات بجوار الأحداث التي تريد استلامها. يمكنك:
اختيار الأحداث الفرعية الفردية (مثل dispute.accepted، dispute.challenged)
اختيار الأحداث الرئيسية لاستلام جميع الأحداث الفرعية ذات الصلة
مزج ومطابقة الأحداث المحددة بناءً على احتياجاتك
مراجعة تفاصيل الحدث
مرر فوق رمز المعلومات (ⓘ) بجوار كل حدث لرؤية وصف متى يتم تشغيل هذا الحدث.
حفظ التكوين
انقر على حفظ لتطبيق التغييرات الخاصة بك، أو إلغاء للتراجع عن التعديلات.
إذا قمت بإلغاء تحديد جميع الأحداث، فلن تستقبل نقطة نهاية Webhook الخاصة بك أي إشعارات. تأكد من تحديد الأحداث التي يحتاجها تطبيقك للعمل بشكل صحيح.
تسليم Webhook
المهلات
تحتوي Webhooks على نافذة مهلة مدتها 15 ثانية لكل من عمليات الاتصال والقراءة. تأكد من أن نقطة النهاية الخاصة بك تستجيب بسرعة لتجنب المهلات.
قم بمعالجة Webhooks بشكل غير متزامن من خلال تأكيد الاستلام على الفور مع رمز الحالة 200، ثم التعامل مع المعالجة الفعلية في الخلفية.
إعادة المحاولة التلقائية
إذا فشلت عملية تسليم Webhook، فإن مدفوعات Dodo تعيد المحاولة تلقائيًا مع التراجع الأسي لمنع إرهاق نظامك.
المحاولة التأخير الوصف 1 على الفور تحدث المحاولة الأولى على الفور 2 5 ثوانٍ المحاولة الثانية بعد تأخير قصير 3 5 دقائق المحاولة الثالثة مع زيادة التراجع 4 30 دقيقة المحاولة الرابعة مع استمرار التراجع 5 ساعتان المحاولة الخامسة مع تأخير ممتد 6 5 ساعات المحاولة السادسة مع تأخير أطول 7 10 ساعات المحاولة السابعة مع أقصى تأخير 8 10 ساعات المحاولة النهائية - يتم وضع علامة على 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.
TypeScript/Node.js
Python
Go
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 القياسية:
قم ببناء الرسالة الموقعة عن طريق دمج webhook-id، webhook-timestamp، والسلسلة الخام الدقيقة payload، مفصولة بنقاط (.).
احسب HMAC SHA256 لتلك السلسلة باستخدام مفتاح Webhook السري الخاص بك من لوحة المعلومات.
قارن التوقيع المحسوب مع رأس webhook-signature. إذا تطابقت، فإن Webhook أصلي.
الرد على Webhooks
يجب أن يعيد معالج Webhook الخاص بك 2xx status code للاعتراف باستلام الحدث.
سيتم اعتبار أي استجابة أخرى فاشلة، وسيتم إعادة محاولة Webhook.
أفضل الممارسات
استخدم نقاط نهاية HTTPS فقط
استخدم دائمًا عناوين 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
فهم هيكل حمولة Webhook يساعدك على تحليل ومعالجة الأحداث بشكل صحيح.
تنسيق الطلب
POST /your-webhook-url
Content-Type : application/json
الرؤوس
معرف فريد لهذا الحدث Webhook. استخدم هذا لفحوصات عدم التكرار.
توقيع HMAC SHA256 للتحقق من صحة Webhook.
طابع زمني Unix (بالثواني) عندما تم إرسال Webhook.
جسم الطلب
معرف عملك في مدفوعات Dodo.
نوع الحدث الذي أدى إلى تشغيل هذا Webhook (مثل payment.succeeded، subscription.created).
طابع زمني بتنسيق ISO 8601 عندما حدث الحدث.
حمولة محددة بالحدث تحتوي على معلومات مفصلة حول الحدث. إظهار خصائص كائن البيانات
نوع المورد: Payment، Subscription، Refund، Dispute، أو LicenseKey.
تختلف الحقول الإضافية حسب نوع الحدث. راجع الوثائق الخاصة بالحدث للحصول على المخططات الكاملة.
مثال على الحمولة
{
"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 للتأكد من أن نقطة النهاية الخاصة بك تعمل بشكل صحيح قبل الانتقال إلى الإنتاج.
الوصول إلى واجهة الاختبار
انتقل إلى Webhooks
انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى Settings > Webhooks.
اختر نقطة النهاية الخاصة بك
انقر على نقطة نهاية Webhook الخاصة بك للوصول إلى صفحة التفاصيل الخاصة بها.
فتح علامة التبويب للاختبار
انقر على علامة التبويب الاختبار للوصول إلى واجهة اختبار Webhook.
اختبار Webhook الخاص بك
توفر واجهة الاختبار طريقة شاملة لاختبار نقطة نهاية Webhook الخاصة بك:
اختيار نوع الحدث
استخدم قائمة السحب لاختيار نوع الحدث المحدد الذي تريد اختباره (مثل payment.succeeded، payment.failed، إلخ). تحتوي القائمة المنسدلة على جميع أنواع أحداث Webhook المتاحة التي يمكن لنقطة النهاية الخاصة بك استلامها.
مراجعة المخطط والمثال
تعرض الواجهة كلاً من المخطط (هيكل البيانات) والمثال (حمولة عينة) لنوع الحدث المحدد.
إرسال حدث اختبار
انقر على زر إرسال مثال لإرسال Webhook اختبار إلى نقطة النهاية الخاصة بك. مهم : الرسائل الفاشلة المرسلة عبر واجهة الاختبار لن يتم إعادة محاولة إرسالها. هذا للاختبار فقط.
التحقق من اختبارك
تحقق من نقطة النهاية الخاصة بك
راقب سجلات نقطة نهاية Webhook الخاصة بك لتأكيد استلام حدث الاختبار.
التحقق من التوقيع
تأكد من أن التحقق من التوقيع الخاص بك يعمل بشكل صحيح مع الحمولة الاختبارية.
اختبار الاستجابة
تأكد من أن نقطة النهاية الخاصة بك تعيد رمز الحالة 2xx للاعتراف بالاستلام.
مثال على التنفيذ
إليك تنفيذ كامل باستخدام Express.js يظهر التحقق من Webhook ومعالجته:
Express.js Webhook Handler
Testing Webhooks Locally
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 إلى نقطة النهاية الخاصة بك لمنع إرهاق نظامك.
الوصول إلى إعدادات تحديد المعدل
في علامة المتقدمة ، ابحث عن قسم “تحديد المعدل (تقييد)”.
تكوين تحديد المعدل
انقر على زر تعديل لتعديل إعدادات تحديد المعدل. بشكل افتراضي، تحتوي Webhooks على “لا يوجد تحديد معدل” مطبق، مما يعني أن الأحداث يتم تسليمها بمجرد حدوثها.
تعيين الحدود
قم بتكوين حد تحديد المعدل المطلوب للتحكم في تكرار تسليم Webhook ومنع تحميل النظام.
استخدم تحديد المعدل عندما يحتاج معالج Webhook الخاص بك إلى وقت لمعالجة الأحداث أو عندما تريد تجميع أحداث متعددة معًا.
الرؤوس المخصصة
أضف رؤوس HTTP مخصصة إلى جميع طلبات Webhook المرسلة إلى نقطة النهاية الخاصة بك. هذا مفيد للمصادقة أو التوجيه أو إضافة بيانات وصفية إلى طلبات Webhook الخاصة بك.
إضافة رأس مخصص
في قسم “الرؤوس المخصصة”، أدخل المفتاح والقيمة لرأسك المخصص.
إضافة رؤوس متعددة
انقر على زر + لإضافة رؤوس مخصصة إضافية حسب الحاجة.
حفظ التكوين
سيتم تضمين رؤوسك المخصصة في جميع طلبات Webhook إلى هذه النقطة النهائية.
التحويلات
تسمح لك التحويلات بتعديل حمولة Webhook وإعادة توجيهها إلى عنوان URL مختلف. تتيح لك هذه الميزة القوية:
تعديل هيكل الحمولة قبل المعالجة
توجيه Webhooks إلى نقاط نهاية مختلفة بناءً على المحتوى
إضافة أو إزالة الحقول من الحمولة
تحويل تنسيقات البيانات
تفعيل التحويلات
قم بتبديل مفتاح مفعل لتفعيل ميزة التحويل.
تكوين التحويل
انقر على تعديل التحويل لتعريف قواعد التحويل الخاصة بك. يمكنك استخدام JavaScript لتحويل حمولة Webhook وتحديد عنوان URL مستهدف مختلف.
اختبار التحويل
استخدم واجهة الاختبار للتحقق من أن التحويل الخاص بك يعمل بشكل صحيح قبل الانتقال إلى الإنتاج.
يمكن أن تؤثر التحويلات بشكل كبير على أداء تسليم Webhook. اختبر بدقة واحتفظ بمنطق التحويل بسيطًا وفعالًا.
تكون التحويلات مفيدة بشكل خاص لـ:
تحويل بين تنسيقات البيانات المختلفة
تصفية الأحداث بناءً على معايير محددة
إضافة حقول محسوبة إلى الحمولة
توجيه الأحداث إلى خدمات ميكرو مختلفة
مراقبة سجلات Webhook
توفر علامة السجلات رؤية شاملة لحالة تسليم Webhook الخاصة بك، مما يسمح لك بمراقبة وتصحيح وإدارة أحداث Webhook بشكل فعال.
مراقبة النشاط
توفر علامة النشاط رؤى في الوقت الحقيقي حول أداء تسليم Webhook الخاص بك مع تحليلات بصرية.
تنبيهات البريد الإلكتروني
ابق على اطلاع بصحة Webhook الخاصة بك مع إشعارات البريد الإلكتروني التلقائية. عندما تبدأ عمليات تسليم Webhook في الفشل أو تتوقف نقطة النهاية الخاصة بك عن الاستجابة، ستتلقى تنبيهات عبر البريد الإلكتروني حتى تتمكن من معالجة المشكلات بسرعة والحفاظ على تشغيل تكاملاتك بسلاسة.
تفعيل تنبيهات البريد الإلكتروني
انتقل إلى إعدادات التنبيه
انتقل إلى لوحة معلومات مدفوعات Dodo الخاصة بك وانتقل إلى لوحة المعلومات → Webhooks → التنبيه .
تفعيل إشعارات البريد الإلكتروني
قم بتبديل إشعارات البريد الإلكتروني لبدء تلقي تنبيهات حول مشكلات تسليم Webhook.
تكوين عنوان البريد الإلكتروني
أدخل عنوان البريد الإلكتروني الذي تريد استلام تنبيهات Webhook عليه. سنرسل إشعارات إلى هذا العنوان عندما تحدث أحداث معينة مع إعداد Webhooks الخاص بك، مثل مشكلات التسليم التي قد تؤثر على تكاملاتك.
قم بتفعيل تنبيهات البريد الإلكتروني لالتقاط مشكلات تسليم Webhook مبكرًا والحفاظ على تكاملات موثوقة. ستتلقى إشعارات عندما تفشل التسليمات أو تصبح نقطة النهاية الخاصة بك غير مستجيبة.
النشر على منصات السحابة
هل أنت مستعد لنشر معالج Webhook الخاص بك في الإنتاج؟ نقدم أدلة خاصة بالمنصات لمساعدتك في نشر Webhooks إلى موفري السحابة الشائعة مع أفضل الممارسات لكل منصة.
تتضمن كل دليل منصة إعداد البيئة، والتحقق من التوقيع، وخطوات النشر المحددة لذلك الموفر.