title: "Webhookها" order: 6 description: "رویدادهای خرید، بازپرداخت و اشتراک؛ امضای HMAC-SHA256، تلاش دوباره، لاگ تحویل و نمونه کد بررسی امضا"

Webhookها

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

ثبت Webhook

در کنسول، بخش پرداخت ← Webhookها (یا با API):

کار endpoint
فهرست / ساخت GET / POST /console/v1/billing/orgs/{orgId}/webhooks
ویرایش / حذف PUT / DELETE /console/v1/billing/orgs/{orgId}/webhooks/{id}
لاگ تحویل GET /console/v1/billing/orgs/{orgId}/webhooks/{id}/deliveries?cursor=
ارسال رویداد آزمایشی POST /console/v1/billing/orgs/{orgId}/webhooks/{id}/test
{ "url": "https://example.com/webhooks/balestore", "events": ["purchase.completed", "purchase.refunded"] }

پاسخ ساخت شامل secret است که فقط یک بار نمایش داده می‌شود. آن را امن نگه دارید؛ کلید HMAC همین رشته (بایت‌های UTF-8 آن) است. از نشانی https استفاده کنید.

انواع رویداد

type زمان ارسال
purchase.completed یک خرید (محصول درون‌برنامه‌ای، اشتراک یا برنامهٔ پولی) با موفقیت پرداخت شد
purchase.refunded خریدی کامل یا جزئی بازپرداخت شد (توسط شما، پشتیبانی، یا خودکار به‌خاطر نهایی‌نشدن در مهلت)
subscription.renewed اشتراک برای دورهٔ بعد تمدید شد
subscription.in_grace تمدید ناموفق بود و اشتراک وارد دورهٔ مهلت شد
subscription.expired اشتراک منقضی شد
subscription.canceled اشتراک لغو شد (تا پایان دورهٔ جاری فعال می‌ماند)

قالب درخواست

POST /webhooks/balestore HTTP/1.1
Content-Type: application/json
X-BaleStore-Signature: t=1763539200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{"id":"0e5b8a8c-6c1e-4f43-9d2a-3f2b7f1d9a10","type":"purchase.completed","createdAt":"2026-11-19T08:00:00Z","data":{…}}
فیلد توضیح
id شناسهٔ یکتای رویداد؛ در تلاش‌های دوباره ثابت می‌ماند
type نوع رویداد (جدول بالا)
createdAt زمان رخداد (ISO-8601، UTC)
data جزئیات رویداد

نمونهٔ data برای purchase.completed (شکل نمونه؛ ممکن است فیلدهای بیشتری داشته باشد):

{
  "packageName": "com.example.game",
  "orderId": "6f1c2a7e-3b0d-4b8e-9f51-2f7a0c9d1e44",
  "productId": "coins_100",
  "purchaseToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "purchaseTime": 1763539200000,
  "developerPayload": "order-42",
  "userHash": "9c1f0e…",
  "test": false
}

Webhook را اعلان در نظر بگیرید، نه منبع حقیقت. پیش از هر تصمیم مالی مهم، وضعیت را با API سرور به سرور بخوانید.

بررسی امضا

سرآیند X-BaleStore-Signature به این شکل است:

X-BaleStore-Signature: t=<unix seconds>,v1=<hex(HMAC-SHA256(secret, t + "." + body))>

برای بررسی:

  1. بدنهٔ خام درخواست را همان‌طور که رسیده (بایت به بایت) بخوانید. JSON را پیش از بررسی parse و دوباره serialize نکنید؛ هر تغییر در فاصله‌ها یا ترتیب کلیدها امضا را باطل می‌کند.
  2. t و v1 را از سرآیند جدا کنید (ممکن است بیش از یک v1 بیاید؛ اگر هر کدام درست بود، قبول کنید).
  3. رشتهٔ t (همان‌طور که در سرآیند آمده) + "." + بدنهٔ خام را با secret به روش HMAC-SHA256 امضا کنید و خروجی را با v1 به روش زمان-ثابت (constant-time) مقایسه کنید.
  4. پنجرهٔ زمانی: اگر |now − t| از ۵ دقیقه (۳۰۰ ثانیه، پیشنهادی) بیشتر بود، رد کنید تا جلوی حملهٔ تکرار (replay) گرفته شود. ساعت سرورتان را با NTP همگام نگه دارید.
  5. اگر بررسی شکست خورد، 400 یا 401 برگردانید و چیزی را پردازش نکنید.

Kotlin (JVM)

import java.security.MessageDigest
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import kotlin.math.abs

object BaleStoreWebhookVerifier {
    private const val TOLERANCE_SECONDS = 300L

    fun verify(
        secret: String,
        signatureHeader: String?,
        rawBody: ByteArray,
        nowEpochSeconds: Long = System.currentTimeMillis() / 1000,
    ): Boolean {
        if (signatureHeader.isNullOrBlank()) return false
        var ts: String? = null
        val signatures = mutableListOf<ByteArray>()
        for (part in signatureHeader.split(',')) {
            val kv = part.trim().split('=', limit = 2)
            if (kv.size != 2) continue
            when (kv[0]) {
                "t" -> ts = kv[1]
                "v1" -> hexToBytes(kv[1])?.let { signatures += it }
            }
        }
        val t = ts ?: return false
        val tSeconds = t.toLongOrNull() ?: return false
        if (signatures.isEmpty() || abs(nowEpochSeconds - tSeconds) > TOLERANCE_SECONDS) return false

        val mac = Mac.getInstance("HmacSHA256")
        mac.init(SecretKeySpec(secret.toByteArray(Charsets.UTF_8), "HmacSHA256"))
        mac.update("$t.".toByteArray(Charsets.UTF_8))
        val expected = mac.doFinal(rawBody)
        return signatures.any { MessageDigest.isEqual(expected, it) } // constant-time
    }

    private fun hexToBytes(hex: String): ByteArray? {
        if (hex.length != 64) return null
        val out = ByteArray(32)
        for (i in out.indices) {
            val hi = Character.digit(hex[2 * i], 16)
            val lo = Character.digit(hex[2 * i + 1], 16)
            if (hi < 0 || lo < 0) return null
            out[i] = ((hi shl 4) or lo).toByte()
        }
        return out
    }
}

// Spring Boot: take the body as ByteArray so it is not re-serialized
@PostMapping("/webhooks/balestore")
fun webhook(
    @RequestHeader("X-BaleStore-Signature", required = false) signature: String?,
    @RequestBody body: ByteArray,
): ResponseEntity<Void> {
    if (!BaleStoreWebhookVerifier.verify(webhookSecret, signature, body)) return ResponseEntity.status(401).build()
    val event = objectMapper.readTree(body)
    if (!processedEvents.markIfNew(event["id"].asText())) return ResponseEntity.ok().build() // duplicate
    eventQueue.enqueue(event) // process asynchronously
    return ResponseEntity.ok().build()
}

Go

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const tolerance = 5 * time.Minute

// Verify checks X-BaleStore-Signature against the raw request body.
func Verify(secret []byte, header string, body []byte, now time.Time) error {
	var ts string
	var sigs [][]byte
	for _, part := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(part), "=")
		if !ok {
			continue
		}
		switch k {
		case "t":
			ts = v
		case "v1":
			if b, err := hex.DecodeString(v); err == nil {
				sigs = append(sigs, b)
			}
		}
	}
	if ts == "" || len(sigs) == 0 {
		return errors.New("malformed signature header")
	}
	sec, err := strconv.ParseInt(ts, 10, 64)
	if err != nil {
		return errors.New("bad timestamp")
	}
	if d := now.Sub(time.Unix(sec, 0)); d > tolerance || d < -tolerance {
		return errors.New("timestamp outside tolerance")
	}
	mac := hmac.New(sha256.New, secret)
	mac.Write([]byte(ts))
	mac.Write([]byte("."))
	mac.Write(body)
	expected := mac.Sum(nil)
	for _, s := range sigs {
		if hmac.Equal(expected, s) { // constant-time
			return nil
		}
	}
	return errors.New("signature mismatch")
}

func Handler(secret []byte) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "bad body", http.StatusBadRequest)
			return
		}
		if err := Verify(secret, r.Header.Get("X-BaleStore-Signature"), body, time.Now()); err != nil {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}
		// parse body, dedupe on event id, enqueue for async processing …
		w.WriteHeader(http.StatusOK)
	}
}

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_balestore_signature(secret: str, header: str | None, raw_body: bytes, now: int | None = None) -> bool:
    if not header:
        return False
    ts, sigs = None, []
    for part in header.split(","):
        key, sep, value = part.strip().partition("=")
        if not sep:
            continue
        if key == "t":
            ts = value
        elif key == "v1":
            sigs.append(value.strip().lower())
    if ts is None or not sigs:
        return False
    try:
        t = int(ts)
    except ValueError:
        return False
    now = int(time.time()) if now is None else now
    if abs(now - t) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(secret.encode("utf-8"), ts.encode("utf-8") + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in sigs)  # constant-time

# Flask: request.get_data() returns the raw body
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/balestore")
def balestore_webhook():
    raw = request.get_data()  # call before request.json
    if not verify_balestore_signature(WEBHOOK_SECRET, request.headers.get("X-BaleStore-Signature"), raw):
        abort(401)
    event = request.get_json()
    if already_processed(event["id"]):
        return "", 200
    enqueue(event)
    return "", 200

Node.js

const crypto = require("node:crypto");
const express = require("express");

const TOLERANCE_SECONDS = 300;

function verifyBaleStoreSignature(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
  if (!header) return false;
  let ts = null;
  const sigs = [];
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t") ts = value;
    else if (key === "v1") sigs.push(value);
  }
  if (!ts || !/^\d+$/.test(ts) || sigs.length === 0) return false;
  if (Math.abs(nowSeconds - Number(ts)) > TOLERANCE_SECONDS) return false;

  const expected = crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest();
  return sigs.some((s) => {
    if (!/^[0-9a-fA-F]{64}$/.test(s)) return false;
    const given = Buffer.from(s, "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected); // constant-time
  });
}

const app = express();
// express.raw keeps the body as a Buffer — do NOT use express.json() on this route
app.post("/webhooks/balestore", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyBaleStoreSignature(process.env.BALESTORE_WEBHOOK_SECRET, req.get("X-BaleStore-Signature"), req.body)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // dedupe on event.id, then process asynchronously
  res.sendStatus(200);
});

تحویل، تلاش دوباره و لاگ

  • هر پاسخ 2xx در مهلت زمانی (پیش‌فرض ۵ ثانیه، قابل تنظیم) یعنی تحویل موفق. هر چیز دیگر (خطای شبکه، timeout، 3xx/4xx/5xx) شکست حساب می‌شود.
  • پس از شکست، تحویل با backoff نمایی تکرار می‌شود (پیش‌فرض: شروع از حدود ۳۰ ثانیه، با سقف فاصلهٔ ۶ ساعت؛ قابل تنظیم) تا حداکثر ۷۲ ساعت پس از رویداد. پس از آن وضعیت تحویل GAVE_UP می‌شود.
  • وضعیت‌های تحویل در لاگ کنسول: PENDING، SUCCEEDED، FAILED، RETRYING، GAVE_UP؛ با تعداد تلاش (attempts)، آخرین کد HTTP (lastStatusCode) و زمان تلاش بعدی (nextAttemptAt).
  • با «ارسال آزمایشی» در کنسول، اتصال و بررسی امضای سرورتان را آزمایش کنید.

Idempotency و ترتیب

  • یک رویداد ممکن است بیش از یک بار برسد (مثلاً پاسخ شما پس از timeout رسیده). روی id رویداد dedupe کنید: پیش از پردازش، id را در جدولی با کلید یکتا ثبت کنید و اگر تکراری بود فقط 200 برگردانید.
  • ترتیب رسیدن تضمین نمی‌شود. برای تصمیم‌گیری به createdAt و وضعیت فعلی از API سرور تکیه کنید، نه به ترتیب دریافت.
  • سریع پاسخ دهید: امضا را بررسی کنید، رویداد را در صف بگذارید و 200 برگردانید؛ پردازش سنگین را ناهمگام انجام دهید.

چک‌لیست امنیت

  • امضا روی بدنهٔ خام بررسی می‌شود.
  • مقایسه زمان-ثابت است (MessageDigest.isEqual، hmac.Equal، hmac.compare_digest، crypto.timingSafeEqual).
  • پنجرهٔ زمانی (پیشنهادی ۵ دقیقه) اعمال می‌شود.
  • dedupe روی id انجام می‌شود.
  • secret در کد منبع یا لاگ نیست.
  • نشانی Webhook با https است.