إنتقل إلى المحتوى الرئيسي

نظرة عامة على الـ webhooks

تتيح لك الـ webhooks تلقي إشعارات لحظية بالأحداث التي تقع في حسابك على OrcaRail، مثل نجاح دفعة أو فشلها.

ما هي الـ webhooks؟​

الـ webhooks استدعاءات HTTP راجعة ترسلها OrcaRail إلى خادمك عند وقوع أحداث معينة. بدلًا من استطلاع API بحثًا عن تحديثات، تدفع الـ webhooks بيانات الحدث إلى تطبيقك لحظيًا.

كيف تعمل الـ webhooks​

  1. يقع حدث في OrcaRail (مثل نجاح دفعة)
  2. ترسل OrcaRail طلب HTTP POST إلى نقطة نهاية الـ webhook لديك
  3. يرد خادمك بـ 200 OK لتأكيد الاستلام
  4. يعالج تطبيقك الحدث

إعداد الـ webhooks​

1. أنشئ نقطة نهاية للـ webhook​

أنشئ في تطبيقك نقطة نهاية HTTP يمكنها استقبال طلبات POST:

// Express.js example
app.post('/webhooks/orcarail', express.json(), (req, res) => {
  const event = req.body

  // Process the event
  handleWebhookEvent(event)

  // Always return 200 OK immediately
  res.status(200).json({ received: true })
})

2. اضبط رابط الـ webhook​

اضبط رابط نقطة نهاية الـ webhook عند إنشاء مفتاح API أو تحديثه. يجب أن يكون رابط الـ webhook:

  • متاحًا للعموم — يجب أن تصل إليه OrcaRail من الإنترنت
  • HTTPS — للأمان (إلزامي في الإنتاج)
  • سريعًا — يرد بـ 200 OK خلال 10 ثوانٍ (مهلة الانتظار 10 ثوانٍ)

راجع إعداد الـ webhooks للتعليمات التفصيلية.

3. تحقق من توقيعات الـ webhooks​

تحقق دائمًا من توقيعات الـ webhooks للتأكد من أن الطلبات صادرة فعلًا من OrcaRail. راجع توقيعات الـ webhooks للتفاصيل.

أحداث الـ webhook​

ترسل OrcaRail أحداث webhook لأنشطة مختلفة متعلقة بالمدفوعات:

الحدثالوصف
payment_intent.completedنجح Payment Intent وعولجت الدفعة
payment_intent.processingPayment Intent قيد المعالجة على البلوكتشين
payment_intent.canceledأُلغي Payment Intent
payment_intent.requires_payment_methodيحتاج Payment Intent إلى طريقة دفع

راجع أحداث الـ webhook لمعلومات تفصيلية عن كل نوع حدث.

حمولة الـ webhook​

تتبع كل أحداث الـ webhook هذه البنية:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "metadata": {
        "order_id": "12345"
      }
    }
  }
}

معالجة الـ webhooks​

عدم التكرار (Idempotency)​

قد تُرسل الـ webhooks أكثر من مرة للحدث نفسه. اجعل معالجات الـ webhooks دائمًا idempotent:

const processedEvents = new Set()

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  const event = req.body
  const eventId = `${event.type}_${event.data.object.id}`

  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    return res.status(200).json({ received: true })
  }

  // Process the event
  await handleWebhookEvent(event)

  // Mark as processed
  processedEvents.add(eventId)

  res.status(200).json({ received: true })
})

استجب بسرعة​

استجب دائمًا بـ 200 OK خلال 10 ثوانٍ (مهلة الـ webhook)، ثم عالج الحدث بشكل غير متزامن:

app.post('/webhooks/orcarail', express.json(), (req, res) => {
  const event = req.body

  // Respond immediately
  res.status(200).json({ received: true })

  // Process asynchronously
  processEventAsync(event).catch((error) => {
    console.error('Error processing webhook:', error)
  })
})

معالجة الأخطاء​

إذا أعادت نقطة النهاية رمز حالة غير 200، فستعيد OrcaRail إرسال الـ webhook. نفّذ معالجة أخطاء سليمة:

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  try {
    const event = req.body

    // Verify signature
    verifyWebhookSignature(req)

    // Process event
    await handleWebhookEvent(event)

    res.status(200).json({ received: true })
  } catch (error) {
    console.error('Webhook error:', error)

    // Return 500 to trigger retry, or 200 if you don't want retries
    res.status(500).json({ error: 'Internal server error' })
  }
})

اختبار الـ webhooks​

باستخدام ngrok​

للتطوير المحلي، استخدم ngrok لإتاحة خادمك المحلي:

ngrok http 3000

ثم اضبط رابط الـ webhook على https://your-ngrok-url.ngrok.io/webhooks/orcarail.

الاختبار باستخدام cURL​

يمكنك اختبار نقطة نهاية الـ webhook يدويًا:

curl -X POST https://your-webhook-url.com/webhooks/orcarail \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: your-signature" \
  -d '{
    "type": "payment_intent.completed",
    "data": {
      "object": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "100.00",
        "currency": "usd",
        "status": "succeeded"
      }
    }
  }'

الخطوات التالية​