پرش به محتوای مستندات
Webhook
Events

Webhook

با Webhook، ایجاد سفارش از طریق API را روی یک URL امن دریافت کنید. امضای HMAC را پیش از پردازش هر پیام اعتبارسنجی کنید.

ثبت endpoint

  1. 1یک URL عمومی با HTTPS و پاسخ سریع آماده کنید.
  2. 2URL، رویداد order.created و یک secret بین ۶ تا ۱۲۸ کاراکتر را در پنل API ثبت کنید.
  3. 3امضای هر پیام را بررسی و سپس payload را در queue داخلی خود ذخیره کنید.
  4. 4در کمتر از ۵ ثانیه پاسخ 2xx برگردانید.

هدرها و payload

نوع رویداد هم در هدر و هم در بدنه وجود دارد. اگر secret ثبت شده باشد، امضای SHA-256 در هدر ارسال می‌شود.

هدرهای درخواستhttp
Content-Type: application/json
X-Gift30t-Event: order.created
X-Gift30t-Signature: 9dfbf12d...
order.createdjson
{
  "event": "order.created",
  "timestamp": "2026-07-24T08:30:00.000Z",
  "data": {
    "orderId": 5678,
    "orderReference": "A1234567",
    "amount": 490000,
    "status": "PREPARING",
    "items": 1
  }
}

اعتبارسنجی امضا

مقدار امضا برابر HMAC-SHA256 بدنه JSON با secret شماست. مقایسه را با تابع constant-time انجام دهید.

بررسی امضای HMACjavascript
import crypto from "node:crypto";

function verifyGiftCityWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");

  const receivedBuffer = Buffer.from(signature || "", "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  return (
    receivedBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
  );
}
نمونه endpoint در Expressjavascript
app.post("/webhooks/giftcity", express.json(), (req, res) => {
  const event = req.header("X-Gift30t-Event");
  const signature = req.header("X-Gift30t-Signature");

  if (!verifyGiftCityWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // ابتدا دریافت را ثبت کنید؛ پردازش سنگین را به queue بسپارید.
  queue.add("giftcity-webhook", { event, payload: req.body });
  return res.sendStatus(204);
});

رفتار تحویل

Timeout

حداکثر زمان انتظار سرویس برای پاسخ ۵ ثانیه است.

Retry

در نسخه فعلی retry خودکار انجام نمی‌شود؛ endpoint باید پایدار باشد.

Fail count

هر تحویل ناموفق در پنل به شمارنده خطا اضافه می‌شود.

Success

پس از پاسخ موفق، زمان آخرین فراخوانی ثبت و شمارنده خطا صفر می‌شود.