پیکربندی وب‌هوک

یاد بگیرید چطور برای کلیدهای API اورکاریل وب‌هوک تنظیم کنید تا اعلان لحظه‌ای پرداخت بگیرید.

نمای کلی

وب‌هوک‌ها در OrcaRail در سطح کلید API پیکربندی می‌شوند. هر کلید API می‌تواند آدرس وب‌هوک خودش را داشته باشد که به شما امکان می‌دهد:

• رویدادهای مختلف را به اندپوینت‌های مختلف بفرستید
• برای هر محیط (توسعه، staging، عملیاتی) وب‌هوک جداگانه داشته باشید
• وب‌هوک هر کلید API را مستقل تست کنید

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

گام ۱: ساخت یا ویرایش کلید API

وب‌هوک‌ها هنگام ساخت یا ویرایش کلید API تنظیم می‌شوند. می‌توانید پارامتر webhookUrl را تعیین کنید:

ساخت کلید API با آدرس وب‌هوک

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

:organizationId را با سازمانی که می‌خواهید مدیریت کنید جایگزین کنید. آن را در داشبورد ← تنظیمات سازمان یا با فراخوانی اندپوینت فهرست سازمان‌ها و کپی id سازمان مورد نظر پیدا می‌کنید. توکن bearer باید متعلق به کاربر/نشستی باشد که بتواند همان سازمان را مدیریت کند.

بدنه درخواست:

{
  "name": "Production API Key",
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

پاسخ:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

ویرایش آدرس وب‌هوک کلید API

می‌توانید آدرس وب‌هوک یک کلید API موجود را تغییر دهید:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

بدنه درخواست:

{
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

پاسخ:

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

گام ۲: الزامات آدرس وب‌هوک

آدرس وب‌هوک شما باید این الزامات را داشته باشد:

• HTTPS — در محیط عملیاتی الزامی است (HTTP برای توسعه محلی مجاز است)
• در دسترس عموم — OrcaRail باید از اینترنت به آن برسد
• اندپوینت HTTP معتبر — باید درخواست POST بپذیرد
• پاسخ سریع — باید ظرف ۱۰ ثانیه 200 OK برگرداند (مهلت ۱۰ ثانیه است)

گام ۳: حذف آدرس وب‌هوک

برای توقف دریافت وب‌هوک برای یک کلید API، webhookUrl را null کنید:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

بدنه درخواست:

{
  "webhookUrl": null
}

نمونه کدها

JavaScript/TypeScript

// Create API key with webhook URL
const response = await fetch(
  'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production API Key',
      webhookUrl: 'https://api.example.com/webhooks/orcarail',
    }),
  }
)

const { apiKey, key, secret } = await response.json()
console.log('API Key created:', key)
console.log('Webhook URL:', apiKey.webhookUrl)

// Update webhook URL
const updateResponse = await fetch(
  `https://api.orcarail.com/api/v1/api-keys/${apiKey.id}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      webhookUrl: 'https://api.example.com/webhooks/orcarail-v2',
    }),
  }
)

Python

import requests

# Create API key with webhook URL
response = requests.post(
    'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Production API Key',
        'webhookUrl': 'https://api.example.com/webhooks/orcarail',
    },
)

data = response.json()
api_key = data['apiKey']
print(f"API Key created: {data['key']}")
print(f"Webhook URL: {api_key['webhookUrl']}")

# Update webhook URL
update_response = requests.patch(
    f"https://api.orcarail.com/api/v1/api-keys/{api_key['id']}",
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'webhookUrl': 'https://api.example.com/webhooks/orcarail-v2',
    },
)

cURL

# Create API key with webhook URL
curl -X POST https://api.orcarail.com/api/v1/organizations/org_123/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "webhookUrl": "https://api.example.com/webhooks/orcarail"
  }'

# Update webhook URL
curl -X PATCH https://api.orcarail.com/api/v1/api-keys/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.example.com/webhooks/orcarail-v2"
  }'

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

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

OrcaRail اندپوینت‌هایی برای تست پیکربندی وب‌هوک ارائه می‌دهد:

ارسال وب‌هوک آزمایشی

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

POST /api/v1/webhooks/test/:apiKeyId
Authorization: Bearer YOUR_JWT_TOKEN

پاسخ:

{
  "success": true
}

نمونه:

const response = await fetch(
  'https://api.orcarail.com/api/v1/webhooks/test/1',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const result = await response.json()
console.log('Test webhook sent:', result.success)

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

یک payload سفارشی برای تست پردازشگر وب‌هوک بفرستید:

POST /api/v1/webhooks/test/:apiKeyId/custom
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

بدنه درخواست:

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

پاسخ:

{
  "success": true
}

مشاهده لاگ‌های وب‌هوک

وضعیت تحویل وب‌هوک‌ها را بررسی کنید:

GET /api/v1/webhooks/logs?limit=50&offset=0
Authorization: Bearer YOUR_JWT_TOKEN

پارامترهای کوئری:

پارامتر	نوع	پیش‌فرض	توضیح
limit	number	50	تعداد لاگ‌های برگشتی
offset	number	0	تعداد لاگ‌هایی که رد می‌شوند

پاسخ:

{
  "logs": [
    {
      "id": 1,
      "apiKeyId": 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
}

نمونه:

const response = await fetch(
  'https://api.orcarail.com/api/v1/webhooks/logs?limit=10&offset=0',
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const { logs, total } = await response.json()
console.log(`Found ${total} webhook logs`)
logs.forEach((log) => {
  console.log(`${log.event}: ${log.success ? 'Success' : 'Failed'}`)
})

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

۱. برای هر محیط وب‌هوک جداگانه داشته باشید

برای هر محیط کلیدهای API جداگانه با آدرس وب‌هوک متفاوت بسازید:

// Development
{
  name: "Development API Key",
  webhookUrl: "https://dev.example.com/webhooks/orcarail"
}

// Staging
{
  name: "Staging API Key",
  webhookUrl: "https://staging.example.com/webhooks/orcarail"
}

// Production
{
  name: "Production API Key",
  webhookUrl: "https://api.example.com/webhooks/orcarail"
}

۲. پیش از محیط عملیاتی تست کنید

همیشه پیش از استفاده در محیط عملیاتی اندپوینت وب‌هوک را تست کنید:

1. با اندپوینت تست وب‌هوک مطمئن شوید پردازشگر کار می‌کند
2. لاگ‌های وب‌هوک را برای اطمینان از تحویل موفق بررسی کنید
3. مطمئن شوید اعتبارسنجی امضا درست کار می‌کند

۳. تحویل وب‌هوک را پایش کنید

لاگ‌های وب‌هوک را مرتب بررسی کنید تا مطمئن شوید:

• وب‌هوک‌ها با موفقیت تحویل می‌شوند
• زمان پاسخ قابل قبول است
• خطایی رخ نمی‌دهد

۴. شکست وب‌هوک را مدیریت کنید

OrcaRail وب‌هوک‌های ناموفق را خودکار دوباره ارسال می‌کند:

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

مطمئن شوید اندپوینت وب‌هوک تلاش‌های مجدد را درست مدیریت می‌کند (پردازشگرها را idempotent بنویسید).

۵. برای توسعه محلی از ngrok استفاده کنید

برای توسعه محلی، از ngrok برای در دسترس قرار دادن سرور محلی استفاده کنید:

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

سپس آدرس وب‌هوک را روی آدرس ngrok تنظیم کنید:

https://abc123.ngrok.io/webhooks/orcarail

عیب‌یابی

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

1. وضعیت کلید API را بررسی کنید — مطمئن شوید کلید API فعال است
2. آدرس وب‌هوک را بررسی کنید — مطمئن شوید آدرس درست تنظیم شده است
3. لاگ‌های وب‌هوک را بررسی کنید — خطاهای تحویل را در لاگ‌ها ببینید
4. وب‌هوک را تست کنید — با اندپوینت تست اتصال را بررسی کنید

وب‌هوک 404 برمی‌گرداند

• مطمئن شوید اندپوینت وب‌هوک وجود دارد و درخواست POST می‌پذیرد
• درستی مسیر URL را بررسی کنید
• مطمئن شوید سرور در حال اجرا و در دسترس است

وب‌هوک 500 برمی‌گرداند

• لاگ‌های سرور را برای خطا بررسی کنید
• مطمئن شوید پردازشگر وب‌هوک exception پرتاب نمی‌کند
• حتی اگر پردازش شکست بخورد، 200 OK برگردانید

بررسی امضا ناموفق است

• مطمئن شوید از secret درست (secret کلید API) استفاده می‌کنید
• مطمئن شوید امضا را درست محاسبه می‌کنید
• مطمئن شوید از بدنه خام درخواست (نه JSON تجزیه‌شده) استفاده می‌کنید

قدم‌های بعدی

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