۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مستندات API

وب‌هوک‌ها: خبر کم شدن اعتبار و وضعیت کلید

نشانی HTTPS خودت را در داشبورد ثبت می‌کنی و وقتی حساب به توجه نیاز دارد، 1xAi یک POST با بدنهٔ JSON و امضای HMAC به آن می‌فرستد: کم شدن اعتبار، رسیدن خرج یک کلید به آستانهٔ هشدار، ابطال کلید، انقضای کلید و پرداخت اعتبار جبرانی. هر رویداد تا ۷ بار تلاش می‌شود و تحویل «دست‌کم یک بار» است، پس شناسهٔ رویداد را نگه دار.

آخرین به‌روزرسانی:

فهرست مستندات

وب‌هوک‌ها · ۱

رویدادها

رویدادهای وب‌هوک
نوعکِی فرستاده می‌شود
balance.lowاعتبار قابل خرج به آستانهٔ هشدار کم شدن اعتبار برسد یا از آن پایین‌تر برود؛ یک بار برای هر بار رد شدن، و حداکثر ساعتی یک بار
key.cap_warningخرج یک کلید به ۹۰٪ سقفش برسد؛ یک بار برای هر کلید
key.revokedکلیدی باطل شود: به سقف خرج رسیده (spend_cap)، خودت باطلش کرده‌ای (user) یا پشتیبانی (admin)
key.expiredزمان انقضای یک کلید بگذرد
sla.credit_issuedاعتبار جبرانی یک ماه به کیف پول پرداخت شود (اعتبار جبرانی): ماه شمسی (period، مثل 1405-09)، سازنده، نرخ اعتبار (همان نرخی که درصد را تعیین کرده)، درصد و مبلغ؛ یک بار برای هر اعتبار
affiliate.payout_paidدرخواست برداشت پورسانت نقدی‌ات پرداخت‌شده ثبت شود: شناسهٔ درخواست، مبلغ و زمان ثبت؛ یک بار برای هر درخواست

نشانی‌ها را در داشبورد، بخش وب‌هوک‌ها (/dashboard/webhooks) ثبت می‌کنی؛ هر حساب تا ۵ نشانی. نشانی به حساب شخصی تعلق دارد. برای حسابی که غیرفعال یا حذف شده چیزی فرستاده نمی‌شود.

وب‌هوک‌ها · ۲

درخواستی که می‌گیری

بدنه

json
{
  "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-Signaturev1= و سپس امضای HMAC-SHA256 به شکل hex

همهٔ مبلغ‌ها تومان کامل‌اند. هیچ رویدادی رمز یا هش کلید را ندارد؛ key_prefix همان پیشوند نمایشی کلید است.

وب‌هوک‌ها · ۳

بررسی امضا

  1. بدنهٔ خام درخواست را پیش از هر تجزیهٔ JSON بخوان.
  2. اگر X-1xai-Webhook-Timestamp بیش از ۳۰۰ ثانیه با ساعت تو فاصله دارد، درخواست را رد کن.
  3. HMAC-SHA256 را با رمز همان نشانی (whsec_…، کل رشته) روی «زمان، یک نقطه، بدنهٔ خام» حساب کن.
  4. v1= به‌علاوهٔ hex آن را با X-1xai-Webhook-Signature با مقایسهٔ زمان‌ثابت بسنج.
  5. در ۱۰ ثانیه با یک وضعیت 2xx پاسخ بده و کار را بعد از پاسخ انجام بده.
  6. شناسهٔ رویدادی را که قبلاً پردازش کرده‌ای نادیده بگیر.
Python
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 و یک نام عمومی، بدون نام کاربری و گذرواژه؛ نشانی‌های داخلی و خصوصی پذیرفته نمی‌شوند.