مرجع API وب‌هوک‌ها

مرجع کامل اندپوینت API وب‌هوک‌ها.

آدرس پایه

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

دریافت وب‌هوک

رویدادهای وب‌هوک را از 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
}

رویدادهای وب‌هوک

نوع رویداد	توضیح
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 بدنه درخواست را با secret خود محاسبه کنید
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"
}

منطق تلاش مجدد

اگر اندپوینت شما کد وضعیتی غیر از ۲۰۰ برگرداند یا پاسخ ندهد، OrcaRail وب‌هوک را دوباره ارسال می‌کند:

• حداکثر تلاش: ۳ تلاش (۱ اولیه + ۲ تلاش مجدد)
• راهبرد فاصله‌گذاری: فاصله نمایی که از ۲ ثانیه شروع می‌شود
• مهلت: ۱۰ ثانیه برای هر درخواست

بهترین روش‌ها

1. سریع پاسخ دهید — ظرف ۱۰ ثانیه 200 OK برگردانید (مهلت ۱۰ ثانیه است)
2. ناهمگام پردازش کنید — رویدادها را در jobهای پس‌زمینه پردازش کنید
3. امضا را بررسی کنید — همیشه امضای وب‌هوک را بررسی کنید
4. پردازشگرها را idempotent بنویسید — رویدادهای تکراری را درست مدیریت کنید
5. رویدادها را لاگ کنید — همه رویدادهای دریافتی را برای اشکال‌زدایی ثبت کنید

تست

اندپوینت وب‌هوک خود را تست کنید:

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"
      }
    }
  }'

وب‌هوک آزمایشی

یک رویداد وب‌هوک آزمایشی به آدرس وب‌هوک تنظیم‌شده بفرستید.

POST /webhooks/test/:apiKeyId

احراز هویت

• توکن Bearer (JWT) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
apiKeyId	number	بله	شناسه کلید API

پاسخ

{
  "success": true
}

پاسخ‌های خطا

404 Not Found — کلید API پیدا نشد یا آدرس وب‌هوک تنظیم نشده است:

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

ارسال وب‌هوک سفارشی

یک payload وب‌هوک سفارشی به آدرس وب‌هوک تنظیم‌شده بفرستید.

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
}

دریافت لاگ‌های وب‌هوک

لاگ‌های تحویل وب‌هوک حساب خود را دریافت کنید.

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 که وب‌هوک را فعال کرد
userId	number	شناسه کاربر مالک کلید API
event	string	نوع رویداد (مثلاً payment_intent.completed)
url	string	آدرس وب‌هوکی که فراخوانی شد
statusCode	number	کد وضعیت HTTP برگشتی از اندپوینت وب‌هوک
success	boolean	آیا وب‌هوک با موفقیت تحویل شد
attemptNumber	number	شماره تلاش (۱، ۲ یا ۳)
error	string	پیام خطا در صورت شکست تحویل
response	string	بدنه پاسخ اندپوینت وب‌هوک
createdAt	string	زمان ساخت لاگ به قالب ISO 8601

همچنین ببینید

• راهنمای وب‌هوک — مستندات کامل وب‌هوک
• پیکربندی وب‌هوک — تنظیم وب‌هوک برای کلیدهای API
• رویدادهای وب‌هوک — همه رویدادهای موجود
• امضای وب‌هوک — بررسی امضا