StardDevelopersداشبورد

وب‌هوک‌ها

وقتی وضعیت سفارش عوض می‌شود، Stard یک درخواست POST امضاشده به سرورت می‌فرستد؛ دیگر لازم نیست مدام وضعیت را بپرسی.

جواب کوتاه: وب‌هوک Stard برای هر تغییر وضعیت سفارش یک POST با امضای HMAC-SHA256 به سرورت می‌فرستد؛ امضا را با secret بررسی کن و سریع 2xx برگردان.

ساخت وب‌هوک

در داشبورد ← وب‌هوک‌ها آدرس https سرورت، محیط (test یا live) و رویدادها را انتخاب کن. secret (با پیشوند whsec_) فقط همان لحظه نمایش داده می‌شود؛ آن را در متغیر محیطی نگه دار. با «ارسال آزمایشی» یک رویداد webhook.test می‌گیری و با «لاگ ارسال» نتیجه‌ی هر تحویل را می‌بینی.

در محیط test، سفارش‌ها ۱۵ ثانیه بعد خودکار completed می‌شوند تا کل چرخه را بدون پول واقعی آزمایش کنی.

رویدادها

typeکی
order.createdسفارش ثبت شد
order.pendingدر انتظار انجام
order.processingانجام سفارش شروع شد
order.completedسفارش انجام شد
order.cancelledسفارش لغو/رد شد
order.refundedمبلغ برگشت داده شد
order.failedسفارش ناموفق شد
price.alertقیمت به هدف یک هشدار قیمت رسید
webhook.testرویداد آزمایشی از داشبورد

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

POST به آدرس تو
{
  "id": "evt_8Qe2kV1mZ0xYc3Lb",
  "object": "event",
  "type": "order.completed",
  "environment": "test",
  "created": "2026-10-02T11:20:05Z",
  "api_version": "v1",
  "data": {
    "object": {
      "object": "order",
      "id": "ord_test_4Fh8Kp2Lx9Qa7Rt1",
      "environment": "test",
      "status": "completed",
      "type": "stars",
      "title": "۵۰۰ استارز",
      "quantity": 500,
      "recipient": "@username",
      "amount": {
        "amount": 2198000,
        "currency": "IRT"
      },
      "metadata": {
        "invoice": "INV-1042"
      }
    }
  }
}

هدرها: Stard-Event (نوع رویداد)، Stard-Event-Id (شناسه‌ی یکتا؛ برای جلوگیری از پردازش تکراری نگهش دار) و Stard-Signature.

بررسی امضا

هدر Stard-Signature این شکل را دارد: t=1759404005,v1=5f2b…. مقدار v1 برابر HMAC-SHA256 رشته‌ی t + "." + بدنه‌ی خام با secret توست. حتماً بدنه‌ی خام را امضا کن (قبل از parse) و درخواست‌های قدیمی‌تر از ۵ دقیقه را رد کن. SDKها این کار را آماده دارند.

import express from "express";
import { verifyWebhook } from "./stard.mjs";

const app = express();
// بدنه‌ی خام لازم است؛ JSON parser را برای این مسیر نگذار
app.post("/stard/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook(req.body, req.get("Stard-Signature"), process.env.STARD_WEBHOOK_SECRET);
    if (event.type === "order.completed") {
      // سفارش انجام شد: event.data.object
    }
    res.sendStatus(200);           // سریع ۲xx برگردان؛ کار سنگین را در صف انجام بده
  } catch (e) {
    res.sendStatus(400);
  }
});

تلاش دوباره

هر پاسخ غیر 2xx یا timeout (۱۰ ثانیه) شکست حساب می‌شود و دوباره تلاش می‌شود: ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲، ۶، ۱۲ و ۲۴ ساعت بعد (حداکثر ۸ تلاش). بعد از ۵۰ شکست پیاپی، وب‌هوک غیرفعال می‌شود و از داشبورد دوباره فعالش می‌کنی. ریدایرکت دنبال نمی‌شود. ترتیب رسیدن رویدادها تضمین‌شده نیست؛ همیشه به status داخل سفارش تکیه کن.

امنیت

  • فقط آدرس https عمومی پذیرفته می‌شود؛ آدرس‌های داخلی (localhost، 10.x، 192.168.x، 169.254.x و…) رد می‌شوند.
  • secret را می‌توانی هر وقت از داشبورد بچرخانی؛ secret قبلی بلافاصله باطل می‌شود.
  • هرگز بدون بررسی امضا به محتوای وب‌هوک اعتماد نکن.

پرسش‌های رایج

اگر سرورم موقتاً پایین باشد رویداد از دست می‌رود؟

نه؛ تا ۸ بار طی ۲۴ ساعت دوباره ارسال می‌شود و از داشبورد هم می‌توانی دستی دوباره بفرستی.

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

در موارد نادر بله؛ با Stard-Event-Id رویدادهای تکراری را نادیده بگیر.