---
title: وب‌هوک‌ها | Stard API
url: https://stard-market.ir/docs/webhooks
markdown: https://stard-market.ir/docs/webhooks.md
language: fa
updated: 2026-11-18
description: وقتی وضعیت سفارش عوض می‌شود، Stard یک درخواست POST امضاشده به سرورت می‌فرستد؛ دیگر لازم نیست مدام وضعیت را بپرسی.
---

# وب‌هوک‌ها

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

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

## ساخت وب‌هوک

در [داشبورد ← وب‌هوک‌ها](https://stard-market.ir/developers/dashboard#webhooks) آدرس 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 به آدرس تو**

```json
{
  "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ها این کار را آماده دارند.

```javascript
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);
  }
});
```

```python
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
<?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` رویدادهای تکراری را نادیده بگیر.
