وبهوکها
وقتی وضعیت سفارش عوض میشود، Stard یک درخواست POST امضاشده به سرورت میفرستد؛ دیگر لازم نیست مدام وضعیت را بپرسی.
ساخت وبهوک
در داشبورد ← وبهوکها آدرس 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 | رویداد آزمایشی از داشبورد |
بدنهی درخواست
{
"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);
}
});from flask import Flask, request, abort
from stard import verify_webhook
app = Flask(__name__)
@app.post("/stard/webhook")
def stard_webhook():
try:
event = verify_webhook(request.get_data(), request.headers.get("Stard-Signature"), STARD_WEBHOOK_SECRET)
except ValueError:
abort(400)
if event["type"] == "order.completed":
order = event["data"]["object"]
return "", 200<?php
require 'Stard.php';
$raw = file_get_contents('php://input');
try {
$event = Stard\verify_webhook($raw, $_SERVER['HTTP_STARD_SIGNATURE'] ?? '', getenv('STARD_WEBHOOK_SECRET'));
} catch (UnexpectedValueException $e) {
http_response_code(400);
exit;
}
if ($event['type'] === 'order.completed') {
$order = $event['data']['object'];
}
http_response_code(200);تلاش دوباره
هر پاسخ غیر 2xx یا timeout (۱۰ ثانیه) شکست حساب میشود و دوباره تلاش میشود: ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲، ۶، ۱۲ و ۲۴ ساعت بعد (حداکثر ۸ تلاش). بعد از ۵۰ شکست پیاپی، وبهوک غیرفعال میشود و از داشبورد دوباره فعالش میکنی. ریدایرکت دنبال نمیشود. ترتیب رسیدن رویدادها تضمینشده نیست؛ همیشه به status داخل سفارش تکیه کن.
امنیت
- فقط آدرس https عمومی پذیرفته میشود؛ آدرسهای داخلی (localhost، 10.x، 192.168.x، 169.254.x و…) رد میشوند.
- secret را میتوانی هر وقت از داشبورد بچرخانی؛ secret قبلی بلافاصله باطل میشود.
- هرگز بدون بررسی امضا به محتوای وبهوک اعتماد نکن.
پرسشهای رایج
اگر سرورم موقتاً پایین باشد رویداد از دست میرود؟
نه؛ تا ۸ بار طی ۲۴ ساعت دوباره ارسال میشود و از داشبورد هم میتوانی دستی دوباره بفرستی.
ممکن است یک رویداد دو بار برسد؟
در موارد نادر بله؛ با Stard-Event-Id رویدادهای تکراری را نادیده بگیر.
