پرش به مطلب اصلی

نمای کلی وب‌هوک‌ها

وب‌هوک‌ها به شما امکان می‌دهند درباره رویدادهای حساب OrcaRail، مثل موفق یا ناموفق شدن پرداخت، اعلان لحظه‌ای دریافت کنید.

وب‌هوک چیست؟​

وب‌هوک‌ها callbackهای HTTP هستند که OrcaRail هنگام رخ دادن رویدادهای مشخص به سرور شما می‌فرستد. به‌جای پرس‌وجوی دوره‌ای از API برای تغییرات، وب‌هوک‌ها داده رویداد را لحظه‌ای به اپلیکیشن شما می‌فرستند.

وب‌هوک‌ها چطور کار می‌کنند​

  1. رویدادی در OrcaRail رخ می‌دهد (مثلاً پرداختی موفق می‌شود)
  2. OrcaRail یک درخواست HTTP POST به اندپوینت وب‌هوک شما می‌فرستد
  3. سرور شما برای تأیید دریافت با 200 OK پاسخ می‌دهد
  4. اپلیکیشن شما رویداد را پردازش می‌کند

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

۱. یک اندپوینت وب‌هوک بسازید​

در اپلیکیشن خود یک اندپوینت 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 })
})

۲. آدرس وب‌هوک را تنظیم کنید​

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

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

برای راهنمای کامل پیکربندی وب‌هوک را ببینید.

۳. امضای وب‌هوک‌ها را بررسی کنید​

همیشه امضای وب‌هوک‌ها را بررسی کنید تا مطمئن شوید درخواست‌ها واقعاً از OrcaRail آمده‌اند. برای جزئیات امضای وب‌هوک را ببینید.

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

OrcaRail برای فعالیت‌های مختلف مربوط به پرداخت رویداد وب‌هوک می‌فرستد:

رویدادتوضیح
payment_intent.completedیک Payment Intent موفق شده و پرداخت پردازش شده است
payment_intent.processingیک Payment Intent روی بلاکچین در حال پردازش است
payment_intent.canceledیک Payment Intent لغو شده است
payment_intent.requires_payment_methodیک Payment Intent به روش پرداخت نیاز دارد

برای اطلاعات کامل هر نوع رویداد رویدادهای وب‌هوک را ببینید.

payload وب‌هوک​

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

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

پردازش وب‌هوک‌ها​

idempotency​

ممکن است وب‌هوک یک رویداد چند بار ارسال شود. همیشه پردازشگرهای وب‌هوک را 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 پاسخ دهید و سپس رویداد را به‌صورت ناهمگام پردازش کنید:

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)
  })
})

مدیریت خطا​

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

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

تست وب‌هوک‌ها​

با ngrok​

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

ngrok http 3000

سپس آدرس وب‌هوک را https://your-ngrok-url.ngrok.io/webhooks/orcarail تنظیم کنید.

با cURL​

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

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

قدم‌های بعدی​