مستندات وبسرویس

(v1.0)

نیاز به راهنمایی دارید؟

تیم پشتیبانی ما آماده کمک به شماست.

تماس با پشتیبانی

Webhook

با استفاده از Webhook، می‌توانید از رویدادهای مهم مانند تکمیل سفارش یا تغییر وضعیت سفارش به صورت لحظه‌ای مطلع شوید. این امکان به شما اجازه می‌دهد تا به جای بررسی مداوم وضعیت، به محض تغییر وضعیت، اقدامات لازم را انجام دهید.

نحوه کار Webhook

Webhook روشی است که به گیفت سیتی اجازه می‌دهد تا اطلاعات مربوط به رویدادهای خاص را به صورت خودکار به URL مشخص شده توسط شما ارسال کند. برای استفاده از Webhook، باید مراحل زیر را انجام دهید:

  1. یک اندپوینت در سیستم خود ایجاد کنید که بتواند درخواست‌های POST را دریافت و پردازش کند.
  2. در پنل کاربری گیفت سیتی، به بخش API > تنظیمات Webhook بروید.
  3. URL اندپوینت خود و رویدادهای مورد نظر برای دریافت اعلان را مشخص کنید.
  4. در صورت تمایل، یک کلید امنیتی (Secret) برای تأیید اعتبار درخواست‌ها تعیین کنید.

تأیید اعتبار درخواست‌های Webhook

برای اطمینان از اینکه درخواست‌های دریافتی واقعاً از طرف گیفت سیتی ارسال شده‌اند، می‌توانید از هدرX-Gift30t-Signature استفاده کنید. این هدر حاوی امضای HMAC-SHA256 محتوای درخواست با استفاده از کلید امنیتی شماست.

// نمونه تأیید اعتبار درخواست Webhook در Node.js
const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(body)).digest('hex');
  return digest === signature;
}

// در اندپوینت خود
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-gift30t-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, 'YOUR_WEBHOOK_SECRET');
  
  if (!isValid) {
    return res.status(401).send('امضای نامعتبر');
  }
  
  // پردازش رویداد
  // ...
  
  res.status(200).send('دریافت شد');
});

رویدادهای قابل دریافت

نام رویدادتوضیحات
order.createdیک سفارش جدید ایجاد شده است
order.status_changedوضعیت یک سفارش تغییر کرده است
order.completedیک سفارش تکمیل شده و کدها آماده تحویل هستند
order.failedپردازش یک سفارش با مشکل مواجه شده است
wallet.low_balanceموجودی کیف پول از حد تعیین شده کمتر شده است

ساختار پیام‌های Webhook

هر پیام Webhook شامل اطلاعات زیر است:

{
  "event": "order.completed",
  "timestamp": "2023-05-15T10:32:10Z",
  "data": {
    // اطلاعات مرتبط با رویداد
  }
}

بسته به نوع رویداد، بخش data حاوی اطلاعات مختلفی خواهد بود. در ادامه، نمونه‌هایی از ساختار data برای هر رویداد ارائه شده است:

order.created

{
  "event": "order.created",
  "timestamp": "2023-05-15T10:30:45Z",
  "data": {
    "orderId": 5678,
    "orderReference": "1234567",
    "amount": 490000,
    "status": "PREPARING",
    "items": 1
  }
}

order.status_changed

{
  "event": "order.status_changed",
  "timestamp": "2023-05-15T10:31:30Z",
  "data": {
    "orderId": 5678,
    "orderReference": "1234567",
    "oldStatus": "PREPARING",
    "newStatus": "COMPLETED"
  }
}

order.completed

{
  "event": "order.completed",
  "timestamp": "2023-05-15T10:32:10Z",
  "data": {
    "orderId": 5678,
    "orderReference": "1234567",
    "completedAt": "2023-05-15T10:32:10Z",
    "items": [
      {
        "id": 9876,
        "productId": 123,
        "productName": "گیفت کارت استیم 10 دلاری",
        "voucherCode": "STEAM-XXXX-XXXX-XXXX"
      }
    ]
  }
}

نکات مهم

  • اطمینان حاصل کنید که اندپوینت Webhook شما در کمتر از 10 ثانیه پاسخ دهد، در غیر این صورت درخواست لغو خواهد شد.
  • در صورت عدم دریافت کد 200 از اندپوینت شما، گیفت سیتی تا 3 بار دیگر درخواست را مجدداً ارسال خواهد کرد.
  • برای امنیت بیشتر، حتماً از تأیید اعتبار درخواست‌ها با استفاده از X-Gift30t-Signature استفاده کنید.