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

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

OrcaRail رویدادهای وب‌هوک را می‌فرستد تا شما را از تغییرات Payment Intentها و دیگر منابع مطلع کند.

ساختار رویداد​

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

{
  "type": "payment_intent.completed",
  "livemode": true,
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "paymentMethodTypes": ["crypto"],
      "metadata": {
        "order_id": "12345"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

برای رویدادهای یک سازمان sandbox (شبکه‌های آزمایشی، بدون وجوه واقعی) مقدار livemode برابر false است. هرگز سفارش واقعی را بر اساس رویدادهای livemode: false تحویل ندهید. پرداخت‌های شبیه‌سازی‌شده sandbox همچنین latest_transaction.simulated: true دارند.

رویدادهای Payment Intent​

payment_intent.completed​

وقتی Payment Intent موفق شده و پرداخت پردازش شده ارسال می‌شود. (ممکن است در نمونه‌های قدیمی payment_intent.succeeded را ببینید؛ آن را نام دیگر payment_intent.completed در نظر بگیرید.)

نوع رویداد: payment_intent.completed

Payload:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "paymentMethodTypes": ["crypto"],
      "metadata": {
        "order_id": "12345"
      },
      "latestTransaction": {
        "id": "txn_1234567890",
        "status": "completed",
        "hash": "0x1234567890abcdef...",
        "amount": "100.00",
        "currency": "usd"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

چه زمانی استفاده کنیم:

  • تحویل سفارش‌ها
  • ارسال ایمیل تأیید
  • به‌روزرسانی پایگاه داده
  • اجرای جریان‌های تحویل

نمونه پردازشگر:

async function handlePaymentIntentSucceeded(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Fulfill the order
  await fulfillOrder(orderId)

  // Send confirmation email
  await sendConfirmationEmail(paymentIntent)

  // Update database
  await updateOrderStatus(orderId, 'paid')
}

payment_intent.processing​

وقتی Payment Intent روی بلاکچین در حال پردازش است ارسال می‌شود.

نوع رویداد: payment_intent.processing

Payload:

{
  "type": "payment_intent.processing",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "processing",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

چه زمانی استفاده کنیم:

  • نمایش وضعیت پردازش به مشتریان
  • به‌روزرسانی رابط کاربری برای نشان دادن پرداخت در جریان
  • ثبت رویدادهای پردازش

نمونه پردازشگر:

async function handlePaymentIntentProcessing(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Update order status to processing
  await updateOrderStatus(orderId, 'processing')

  // Notify customer
  await notifyCustomer(orderId, 'Your payment is being processed')
}

payment_intent.canceled​

وقتی Payment Intent لغو می‌شود ارسال می‌شود.

نوع رویداد: payment_intent.canceled

Payload:

{
  "type": "payment_intent.canceled",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "canceled",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

چه زمانی استفاده کنیم:

  • آزاد کردن موجودی رزروشده
  • لغو سفارش‌های در انتظار
  • اطلاع‌رسانی به مشتریان
  • پاک‌سازی منابع

نمونه پردازشگر:

async function handlePaymentIntentCanceled(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Release inventory
  await releaseInventory(orderId)

  // Cancel order
  await cancelOrder(orderId)

  // Notify customer
  await notifyCustomer(orderId, 'Your payment was canceled')
}

payment_intent.requires_payment_method​

وقتی Payment Intent نیاز دارد روش پرداختی به آن متصل شود ارسال می‌شود.

نوع رویداد: payment_intent.requires_payment_method

Payload:

{
  "type": "payment_intent.requires_payment_method",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "requires_payment_method",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

چه زمانی استفاده کنیم:

  • پیگیری نشست‌های پرداخت رهاشده
  • ارسال ایمیل یادآوری
  • به‌روزرسانی تحلیل‌ها

نمونه پردازشگر:

async function handlePaymentIntentRequiresPaymentMethod(event) {
  const paymentIntent = event.data.object

  // Track abandoned pay
  await trackAbandonedPay(paymentIntent.id)

  // Send reminder email after delay
  setTimeout(
    () => {
      sendReminderEmail(paymentIntent)
    },
    24 * 60 * 60 * 1000
  ) // 24 hours
}

پردازش رویدادها​

مسیریاب رویداد​

برای مدیریت انواع مختلف رویداد یک مسیریاب بسازید:

const eventHandlers = {
  'payment_intent.completed': handlePaymentIntentSucceeded,
  'payment_intent.succeeded': handlePaymentIntentSucceeded, // alias
  'payment_intent.processing': handlePaymentIntentProcessing,
  'payment_intent.canceled': handlePaymentIntentCanceled,
  'payment_intent.requires_payment_method':
    handlePaymentIntentRequiresPaymentMethod,
}

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

  // Verify signature
  verifyWebhookSignature(req)

  // Get handler for event type
  const handler = eventHandlers[event.type]

  if (handler) {
    try {
      await handler(event)
    } catch (error) {
      console.error(`Error handling ${event.type}:`, error)
      // Still return 200 to prevent retries if you handle errors internally
    }
  } else {
    console.log(`Unhandled event type: ${event.type}`)
  }

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

idempotency​

مطمئن شوید پردازشگرهایتان idempotent هستند:

const processedEvents = new Map()

async function handlePaymentIntentSucceeded(event) {
  const eventId = `${event.type}_${event.data.object.id}`

  // Check if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed`)
    return
  }

  // Process event
  await fulfillOrder(event.data.object.metadata.order_id)

  // Mark as processed (with timestamp for cleanup)
  processedEvents.set(eventId, Date.now())
}

تست رویدادها​

با اندپوینت تست​

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

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": "completed",
        "paymentMethodTypes": ["crypto"],
        "metadata": {
          "order_id": "test_order_123"
        }
      }
    }
  }'

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