مستندات API
وبهوکها: خبر کم شدن اعتبار و وضعیت کلید
نشانی HTTPS خودت را در داشبورد ثبت میکنی و وقتی حساب به توجه نیاز دارد، 1xAi یک POST با بدنهٔ JSON و امضای HMAC به آن میفرستد: کم شدن اعتبار، رسیدن خرج یک کلید به آستانهٔ هشدار، ابطال کلید، انقضای کلید و پرداخت اعتبار جبرانی. هر رویداد تا ۷ بار تلاش میشود و تحویل «دستکم یک بار» است، پس شناسهٔ رویداد را نگه دار.
آخرین بهروزرسانی:
فهرست مستندات
مسیرهای API
حساب، کلید و تیم
وبهوکها · ۱
رویدادها
| نوع | کِی فرستاده میشود |
|---|---|
balance.low | اعتبار قابل خرج به آستانهٔ هشدار کم شدن اعتبار برسد یا از آن پایینتر برود؛ یک بار برای هر بار رد شدن، و حداکثر ساعتی یک بار |
key.cap_warning | خرج یک کلید به ۹۰٪ سقفش برسد؛ یک بار برای هر کلید |
key.revoked | کلیدی باطل شود: به سقف خرج رسیده (spend_cap)، خودت باطلش کردهای (user) یا پشتیبانی (admin) |
key.expired | زمان انقضای یک کلید بگذرد |
sla.credit_issued | اعتبار جبرانی یک ماه به کیف پول پرداخت شود (اعتبار جبرانی): ماه شمسی (period، مثل 1405-09)، سازنده، نرخ اعتبار (همان نرخی که درصد را تعیین کرده)، درصد و مبلغ؛ یک بار برای هر اعتبار |
affiliate.payout_paid | درخواست برداشت پورسانت نقدیات پرداختشده ثبت شود: شناسهٔ درخواست، مبلغ و زمان ثبت؛ یک بار برای هر درخواست |
نشانیها را در داشبورد، بخش وبهوکها (/dashboard/webhooks) ثبت میکنی؛ هر حساب تا ۵ نشانی. نشانی به حساب شخصی تعلق دارد. برای حسابی که غیرفعال یا حذف شده چیزی فرستاده نمیشود.
وبهوکها · ۲
درخواستی که میگیری
بدنه
{
"id": "evt_0123456789abcdef0123456789abcdef",
"type": "balance.low",
"created_at": "2026-11-17T08:30:30Z",
"api_version": "2026-11-17",
"data": { "spendable_toman": 48000, "threshold_toman": 50000 }
}| هدر | مقدار |
|---|---|
X-1xai-Webhook-Id | شناسهٔ رویداد؛ در همهٔ تلاشها یکی است و با id بدنه برابر است |
X-1xai-Webhook-Event | نوع رویداد |
X-1xai-Webhook-Attempt | شمارهٔ تلاش |
X-1xai-Webhook-Timestamp | زمان همین تلاش به ثانیهٔ یونیکس |
X-1xai-Webhook-Signature | v1= و سپس امضای HMAC-SHA256 به شکل hex |
همهٔ مبلغها تومان کاملاند. هیچ رویدادی رمز یا هش کلید را ندارد؛ key_prefix همان پیشوند نمایشی کلید است.
وبهوکها · ۳
بررسی امضا
- بدنهٔ خام درخواست را پیش از هر تجزیهٔ JSON بخوان.
- اگر
X-1xai-Webhook-Timestampبیش از ۳۰۰ ثانیه با ساعت تو فاصله دارد، درخواست را رد کن. - HMAC-SHA256 را با رمز همان نشانی (
whsec_…، کل رشته) روی «زمان، یک نقطه، بدنهٔ خام» حساب کن. v1=بهعلاوهٔ hex آن را باX-1xai-Webhook-Signatureبا مقایسهٔ زمانثابت بسنج.- در ۱۰ ثانیه با یک وضعیت
2xxپاسخ بده و کار را بعد از پاسخ انجام بده. - شناسهٔ رویدادی را که قبلاً پردازش کردهای نادیده بگیر.
import hashlib, hmac, time
def verify_1xai_webhook(secret: str, headers, raw_body: bytes) -> bool:
"""raw_body is the request body exactly as received, before any JSON parsing."""
timestamp = headers.get("X-1xai-Webhook-Timestamp", "")
signature = headers.get("X-1xai-Webhook-Signature", "")
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
return False
signed = timestamp.encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)وبهوکها · ۴
تحویل و تلاش دوباره
- موفقیت یعنی هر پاسخ
2xx. هر چیز دیگر (وضعیت دیگر، ریدایرکت، مهلت، خطای TLS) تلاش ناموفق است. - تا ۷ تلاش برای هر رویداد و هر نشانی، با فاصلههایی که هر بار بلندتر میشوند؛ آخرین تلاش حدود یک روز پس از اولی است.
- ترتیب رویدادها تضمین نمیشود و یک رویداد ممکن است دو بار برسد.
- پس از هر تلاش ناموفق، تا مدتی چیزی به همان نشانی فرستاده نمیشود: ۳۰ ثانیه پس از اولین شکست، که با هر شکست پشتسرهم دو برابر میشود تا یک ساعت. رویدادها در این مدت منتظر میمانند. یک تحویل موفق این مکث را تمام میکند.
- برای هر حساب حداکثر ۳۰ ارسال در دقیقه و ۳۰۰ ارسال در ساعت (رویداد آزمایشی هم شمرده میشود). تحویلی که از این سقف بگذرد در صف منتظر میماند و دور ریخته نمیشود.
- برای هر حساب تا ۵۰۰ تحویل در صف میماند؛ رویدادی که ۷۲ ساعت در صف مانده باشد دیگر فرستاده نمیشود.
- نشانیای که ۲۰ تلاش آخرش همه ناموفق باشند و اولین آنها دستکم ۲۴ ساعت پیش باشد، خاموش میشود و یک ایمیل میگیری. از داشبورد دوباره روشنش میکنی؛ شمار شکستها تا اولین تحویل موفق میماند، پس اگر دوباره شکست بخورد با شکست بعدی دوباره خاموش میشود.
- گزارش هر تحویل (هر تلاش با زمان، وضعیت و نتیجه) در داشبورد هست و ۳۰ روز میماند، و برای هر حساب ۲۰۰ تحویل آخر. از همانجا رویداد آزمایشی هم میفرستی: حداکثر ۵ در دقیقه و ۵۰ در روز.
- نشانی باید
https://باشد، روی درگاه443یا8443و یک نام عمومی، بدون نام کاربری و گذرواژه؛ نشانیهای داخلی و خصوصی پذیرفته نمیشوند.