مرجع API الـ webhooks

مرجع كامل لنقطة نهاية API الـ webhooks.

الرابط الأساسي

https://api.orcarail.com/api/v1

استقبال webhook

استقبل أحداث الـ webhook من OrcaRail.

POST /webhooks

المصادقة

• مفتاح API (Basic Auth) — اختياري لكنه موصى به

الترويسات

الترويسة	النوع	مطلوبة	الوصف
x-webhook-signature	string	مشروطة	توقيع HMAC SHA-256 (مطلوب إذا كان PAYMENTS_WEBHOOK_SECRET مضبوطًا)
Content-Type	string	نعم	يجب أن يكون application/json

جسم الطلب

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

الاستجابة

أعِد دائمًا 200 OK فورًا:

{
  "received": true
}

أحداث الـ webhook

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

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

إذا كان PAYMENTS_WEBHOOK_SECRET مضبوطًا، فتحقق من التوقيع:

1. احصل على التوقيع من ترويسة x-webhook-signature
2. احسب HMAC SHA-256 لجسم الطلب باستخدام سرّك
3. قارن التوقيعات باستخدام مقارنة آمنة زمنيًا

مثال: Node.js

const crypto = require('crypto')

function verifySignature(receivedSignature, payload, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  const receivedBuffer = Buffer.from(receivedSignature)
  const expectedBuffer = Buffer.from(expectedSignature)

  if (receivedBuffer.length !== expectedBuffer.length) {
    return false
  }

  return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

متطلبات الاستجابة

استجابة النجاح

أعِد دائمًا 200 OK مع {"received": true} فورًا، حتى لو فشلت المعالجة:

{
  "received": true
}

استجابة الخطأ

إذا فشل التحقق من التوقيع، فأعِد 400 Bad Request:

{
  "statusCode": 400,
  "message": "Invalid webhook signature",
  "error": "Bad Request"
}

منطق إعادة المحاولة

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

• الحد الأقصى للمحاولات: 3 محاولات (1 أولية + 2 إعادة)
• استراتيجية التأخير: تأخير أُسّي يبدأ من ثانيتين
• مهلة الانتظار: 10 ثوانٍ لكل طلب

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

1. استجب بسرعة — أعِد 200 OK خلال 10 ثوانٍ (مهلة الانتظار 10 ثوانٍ)
2. عالِج بشكل غير متزامن — عالِج الأحداث في مهام خلفية
3. تحقق من التوقيعات — تحقق دائمًا من توقيعات الـ webhooks
4. اجعل المعالجات idempotent — تعامل مع الأحداث المكررة بسلاسة
5. سجّل الأحداث — سجّل كل الأحداث المستلمة لتصحيح الأخطاء

الاختبار

اختبر نقطة نهاية الـ webhook:

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

webhook تجريبي

أرسل حدث webhook تجريبيًا إلى رابط الـ webhook المضبوط.

POST /webhooks/test/:apiKeyId

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات المسار

المعامل	النوع	مطلوب	الوصف
apiKeyId	number	نعم	معرّف مفتاح API

الاستجابة

{
  "success": true
}

استجابات الأخطاء

404 Not Found — مفتاح API غير موجود أو رابط الـ webhook غير مضبوط:

{
  "statusCode": 404,
  "message": "Webhook URL not configured for this API key",
  "error": "Not Found"
}

إرسال webhook مخصص

أرسل حمولة webhook مخصصة إلى رابط الـ webhook المضبوط.

POST /webhooks/test/:apiKeyId/custom

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات المسار

المعامل	النوع	مطلوب	الوصف
apiKeyId	number	نعم	معرّف مفتاح API

جسم الطلب

{
  "payload": {
    "type": "payment_intent.completed",
    "data": {
      "object": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "100.00",
        "currency": "usd",
        "status": "succeeded"
      }
    }
  }
}

الاستجابة

{
  "success": true
}

الحصول على سجلات الـ webhooks

استرجع سجلات تسليم الـ webhooks لحسابك.

GET /webhooks/logs

المصادقة

• رمز Bearer (JWT) — مطلوب

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
limit	number	50	عدد السجلات المُعادة
offset	number	0	عدد السجلات المتخطّاة

الاستجابة

{
  "logs": [
    {
      "id": 1,
      "apiKeyId": 1,
      "userId": 1,
      "event": "payment_intent.completed",
      "url": "https://api.example.com/webhooks/orcarail",
      "statusCode": 200,
      "success": true,
      "attemptNumber": 1,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

حقول كائن السجل

الحقل	النوع	الوصف
id	number	معرّف فريد للسجل
apiKeyId	number	معرّف مفتاح API الذي أطلق الـ webhook
userId	number	معرّف المستخدم مالك مفتاح API
event	string	نوع الحدث (مثل payment_intent.completed)
url	string	رابط الـ webhook الذي استُدعي
statusCode	number	رمز حالة HTTP الذي أعادته نقطة نهاية الـ webhook
success	boolean	ما إذا سُلّم الـ webhook بنجاح
attemptNumber	number	رقم المحاولة (1 أو 2 أو 3)
error	string	رسالة الخطأ إذا فشل التسليم
response	string	جسم الاستجابة من نقطة نهاية الـ webhook
createdAt	string	طابع زمني ISO 8601 لإنشاء السجل

انظر أيضًا

• دليل الـ webhooks — توثيق مفصّل للـ webhooks
• إعداد الـ webhooks — اضبط الـ webhooks لمفاتيح API
• أحداث الـ webhook — كل الأحداث المتاحة
• توقيعات الـ webhooks — التحقق من التوقيع