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))>
برای بررسی:
- بدنهٔ خام درخواست را همانطور که رسیده (بایت به بایت) بخوانید. JSON را پیش از بررسی parse و دوباره serialize نکنید؛ هر تغییر در فاصلهها یا ترتیب کلیدها امضا را باطل میکند.
tوv1را از سرآیند جدا کنید (ممکن است بیش از یکv1بیاید؛ اگر هر کدام درست بود، قبول کنید).- رشتهٔ
t(همانطور که در سرآیند آمده) +"."+ بدنهٔ خام را باsecretبه روش HMAC-SHA256 امضا کنید و خروجی را باv1به روش زمان-ثابت (constant-time) مقایسه کنید. - پنجرهٔ زمانی: اگر
|now − t|از ۵ دقیقه (۳۰۰ ثانیه، پیشنهادی) بیشتر بود، رد کنید تا جلوی حملهٔ تکرار (replay) گرفته شود. ساعت سرورتان را با NTP همگام نگه دارید. - اگر بررسی شکست خورد،
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است.