تصحيح أخطاء خطافات الويب دون النشر: صندوق بريد وارد مؤقت يمكنك تشغيله خلال 10 ثوانٍ

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

يضيع كلا سير العمل الوقت على البنية التحتية عندما يكون السؤال الحقيقي بسيطًا: *كيف تبدو الحمولة؟*

يمنحك صندوق الوارد الخاص بـ Botoi على الويب عنوان URL يمكن التخلص منه والذي يلتقط الحمولات الواردة ويخزنها لمدة 24 ساعة. ثلاث مكالمات API. لا حسابات ولا أنفاق ولا خوادم.

سير العمل من 3 خطوات

1. إنشاء بريد وارد للحصول على عنوان URL فريد للاستلام
2. أشر إلى مصدر خطاف الويب الخاص بك على عنوان URL هذا
3. قائمة الحمولات لتفقد ما وصل

كل خطوة هي واحدة curl يأمر.

الخطوة 1: إنشاء صندوق الوارد

curl -X POST https://api.botoi.com/v1/webhook/inbox/create

إجابة:

{
  "success": true,
  "data": {
    "inbox_id": "a1b2c3d4",
    "url": "https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive",
    "expires_in": 86400
  }
}

احفظ inbox_id و url قيم. يبقى البريد الوارد لمدة 24 ساعة (86400 ثانية). يتم حذف عنوان URL وجميع الحمولات المخزنة.

الخطوة 2: أرسل خطافًا عبر الويب إلى البريد الوارد

قم بتوجيه موفر خدمة webhook الخاص بك إلى url من الخطوة 1. يقبل البريد الوارد أي نص JSON:

curl -X POST https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive \\
  -H "Content-Type: application/json" \\
  -d '{
    "event": "payment_intent.succeeded",
    "amount": 4999,
    "currency": "usd",
    "customer_email": "buyer@example.com"
  }'

إجابة:

{
  "success": true,
  "data": {
    "received": true,
    "payload_id": "e5f6g7h8"
  }
}

الخطوة 3: فحص الحمولات

curl -X POST https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/list

إجابة:

{
  "success": true,
  "data": {
    "inbox_id": "a1b2c3d4",
    "payloads": [
      {
        "id": "e5f6g7h8",
        "received_at": "2026-03-26T10:00:00Z",
        "body": {
          "event": "payment_intent.succeeded",
          "amount": 4999,
          "currency": "usd",
          "customer_email": "buyer@example.com"
        }
      }
    ],
    "count": 1
  }
}

يتم تخزين كل حمولة بطابع زمني ومعرف فريد. يمكنك الاتصال بنقطة نهاية القائمة عدة مرات كما تريد ضمن نافذة 24 ساعة.

مثال من العالم الحقيقي: تصحيح أخطاء خطاف الويب Stripe

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

1. قم بإنشاء البريد الوارد

INBOX=\$(curl -s -X POST https://api.botoi.com/v1/webhook/inbox/create)
INBOX_ID=\$(echo \$INBOX | jq -r '.data.inbox_id')
INBOX_URL=\$(echo \$INBOX | jq -r '.data.url')
echo "Inbox URL: \$INBOX_URL"

2. أضف عنوان URL إلى Stripe

اذهب الى لوحة تحكم الشريط > المطورين > خطافات الويب. انقر فوق "إضافة نقطة نهاية" والصق INBOX_URL. حدد الأحداث التي تهمك، مثل payment_intent.succeeded و invoice.payment_failed.

3. قم بتشغيل حدث اختباري

انقر فوق "إرسال اختبار webhook" في لوحة معلومات Stripe. ثم تفقد ما وصل:

curl -s -X POST "https://api.botoi.com/v1/webhook/inbox/\$INBOX_ID/list" | jq '.data.payloads'

لديك الآن الحمولة الدقيقة التي يرسلها Stripe، مع جميع الكائنات المتداخلة وأسماء الحقول والأنواع. استخدم هذا لكتابة المعالج الخاص بك بثقة بدلاً من التخمين في المخطط.

مثال من العالم الحقيقي: اختبار تكامل GitHub webhook

يتم إطلاق خطافات الويب لمستودع GitHub على أحداث مثل push, pull_request، و issues. إليك كيفية التقاط واحدة دون تشغيل أي تعليمات برمجية محليًا.

1. أنشئ صندوق بريد وارد وقم بتكوين GitHub

# Create the inbox
INBOX=\$(curl -s -X POST https://api.botoi.com/v1/webhook/inbox/create)
INBOX_URL=\$(echo \$INBOX | jq -r '.data.url')
INBOX_ID=\$(echo \$INBOX | jq -r '.data.inbox_id')

# Add webhook to your repo via GitHub API
curl -X POST \\
  -H "Authorization: token \$GITHUB_TOKEN" \\
  -H "Content-Type: application/json" \\
  "https://api.github.com/repos/your-org/your-repo/hooks" \\
  -d "{
    \\"config\\": {
      \\"url\\": \\"\$INBOX_URL\\",
      \\"content_type\\": \\"json\\"
    },
    \\"events\\": [\\"pull_request\\"]
  }"

2. افتح طلب السحب، ثم تحقق من البريد الوارد

curl -s -X POST "https://api.botoi.com/v1/webhook/inbox/\$INBOX_ID/list" \\
  | jq '.data.payloads[0].body | {action, number: .pull_request.number, title: .pull_request.title}'

الإخراج (مثال):

{
  "action": "opened",
  "number": 42,
  "title": "Add rate limiting to /api/orders"
}

يمكنك رؤية البنية الدقيقة التي يرسلها GitHub، بما في ذلك الحقول مثل action, sender, repository، والكامل pull_request هدف. يعد هذا أسرع من قراءة مستندات GitHub وتخمين الحقول التي يتم ملؤها لكل نوع حدث.

أتمتة ذلك: برنامج نصي للاختبار

يقوم برنامج bash النصي هذا بإنشاء صندوق بريد وارد، ويرسل حمولة اختبارية، ويستردها، ويتحقق من الرحلة ذهابًا وإيابًا. احفظه باسم test-webhook.sh وقم بتشغيله لتأكيد عمل التكامل الخاص بك من البداية إلى النهاية.

#!/bin/bash
set -euo pipefail

API="https://api.botoi.com/v1/webhook/inbox"

echo "Creating inbox..."
INBOX=\$(curl -s -X POST "\$API/create")
INBOX_ID=\$(echo "\$INBOX" | jq -r '.data.inbox_id')
INBOX_URL=\$(echo "\$INBOX" | jq -r '.data.url')
echo "Inbox ID: \$INBOX_ID"
echo "Receive URL: \$INBOX_URL"

echo ""
echo "Sending test payload..."
SEND=\$(curl -s -X POST "\$INBOX_URL" \\
  -H "Content-Type: application/json" \\
  -d '{
    "event": "order.created",
    "order_id": "ord_98765",
    "total": 129.99,
    "items": [
      {"sku": "WIDGET-A", "qty": 2},
      {"sku": "GADGET-B", "qty": 1}
    ]
  }')

PAYLOAD_ID=\$(echo "\$SEND" | jq -r '.data.payload_id')
echo "Payload ID: \$PAYLOAD_ID"

echo ""
echo "Retrieving payloads..."
LIST=\$(curl -s -X POST "\$API/\$INBOX_ID/list")
COUNT=\$(echo "\$LIST" | jq -r '.data.count')

if [ "\$COUNT" -ge 1 ]; then
  echo "Success: \$COUNT payload(s) received"
  echo "\$LIST" | jq '.data.payloads[0].body'
else
  echo "Error: no payloads found"
  exit 1
fi

الناتج المتوقع:

Creating inbox...
Inbox ID: a1b2c3d4
Receive URL: https://api.botoi.com/v1/webhook/inbox/a1b2c3d4/receive

Sending test payload...
Payload ID: e5f6g7h8

Retrieving payloads...
Success: 1 payload(s) received
{
  "event": "order.created",
  "order_id": "ord_98765",
  "total": 129.99,
  "items": [
    {"sku": "WIDGET-A", "qty": 2},
    {"sku": "GADGET-B", "qty": 1}
  ]
}

المقارنة: صندوق الوارد botoi مقابل البدائل

ميزة	البريد الوارد لبوتوي	نغروك	webhook.site	RequestBin
وقت الإعداد	أمر تجعيد واحد	تثبيت سطر الأوامر + المصادقة	افتح المتصفح	افتح المتصفح
مطلوب خادم محلي	لا	نعم	لا	لا
الحساب مطلوب	لا	نعم (الطبقة المجانية)	لا (محدود)	نعم
الوصول البرمجي	واجهة برمجة التطبيقات الكاملة	واجهة برمجة التطبيقات (مدفوعة)	واجهة برمجة التطبيقات (مدفوعة)	واجهة برمجة التطبيقات (مدفوعة)
متوافق مع CI/CD	نعم؛ حليقة + JQ	ممكن؛ معقد	لا	لا
TTL	24 ساعة	على أساس الجلسة	يختلف	48 ساعة
تبقى العملية قيد التشغيل	لا	نعم	لا	لا
حر	نعم	محدود	محدود	لا

الميزة الرئيسية لصندوق الوارد الخاص بـ botoi هي أن كل شيء يحدث من خلال واجهة برمجة التطبيقات (API). يمكنك إنشاء صناديق البريد الوارد، وإرسال الاختبار الحمولات النافعة، واسترجاع النتائج داخل نصوص shell، وخطوط أنابيب CI، واختبارات التكامل دون فتح المتصفح أو الحفاظ على عملية الخلفية حية.

متى تستخدم هذا

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

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