منسّق حمولات Webhook

ما هو الـ webhook؟

الـ webhook طلب HTTP ترسله خدمة ما إلى عنوان تسجّله عندما يحدث شيء — تسوية دفعة، أو تسليم رسالة، أو انتهاء بناء — فيتفاعل نظامك مع الأحداث بدلاً من الاستطلاع المتكرر. اختباره يعني التقاط ما يُرسَل فعلياً (الأسلوب والترويسات والجسم)، وفحص إعادة المحاولة والترتيب، والتحقق من التوقيع الذي يثبت أن النداء جاء من المرسِل.

ملاحظة أمنية: نقطة نهاية الـ webhook عنوان عام يمكن لأي شخص الإرسال إليه. تحقق من توقيع المرسِل (عادةً HMAC على الجسم الخام) بمقارنة ثابتة الزمن، وارفض الطوابع الزمنية القديمة، وتعامل مع الحمولة كمدخل غير موثوق.

اقرأ الدليل: ما هو اختبار API؟ وكيف تختبر REST API

كيفية استخدام منسّق حمولات Webhook

1. الصق جسم webhook (وترويسات الطلب إن كانت لديك).
2. تُنسَّق الحمولة فوراً؛ اقرأ النظرة العامة وجدول الحقول المهمة.
3. استخدم جدول الطوابع الزمنية للتحقق من أوقات الأحداث، والشجرة للتنقل في الحمولات الكبيرة.

مزايا منسّق حمولات Webhook

• ينسّق JSON، ويفكّ ترميز الأجسام المرمّزة كنماذج، ويحافظ على XML مقروءاً
• يكتشف المزوّد ونوع الحدث من الجسم والترويسات الاختيارية
• يبرز المعرّفات وأنواع الأحداث والحالات والمبالغ والعملات وعناوين البريد الإلكتروني وعناوين URL
• يحوّل طوابع Unix الزمنية (بالثواني/الملّي ثانية) وطوابع ISO مع الوقت النسبي
• عرض شجري، وترتيب اختياري للمفاتيح، وإحصاءات الحجم، وتنسيق فوري

مثال على منسّق حمولات Webhook

{"id":"evt_1PZx…","type":"payment_intent.succeeded","created":1725184800,"data":{"object":{"amount":19900,"currency":"sar","status":"succeeded"}}}

Provider: Stripe · Event: payment_intent.succeeded · Event id: evt_1PZx…
$.data.object.amount  amount  19900  199.00 if the value is in minor units
$.created  timestamp  1725184800 → 2024-09-01T10:40:00.000Z (about a year ago)

الأسئلة الشائعة حول منسّق حمولات Webhook

المراجع

• RFC 9421: HTTP Message SignaturesIETF · 2024طريقة قياسية لتوقيع رسائل HTTP بحيث يتحقق المستلم من مصدرها وسلامتها — أساس توقيعات webhook الحديثة.
• RFC 2104: HMAC: Keyed-Hashing for Message AuthenticationIETF · 1997بناء HMAC: كيف يُنتج مفتاح سري ودالة تجزئة رمز مصادقة للرسالة.
• OWASP Cheat Sheet Series: REST SecurityOWASP Foundationالقواعد الأمنية لواجهات REST: HTTPS، والتوثيق في كل طلب، والتحقق من المدخلات، واستجابات الخطأ الآمنة، وتحديد المعدل.