Webhooks: low balance and key events
You register an HTTPS address of your own in the dashboard, and when the account needs attention 1xAi sends it a POST with a JSON body and an HMAC signature: a low balance, a key's spend reaching its warning threshold, a key revoked, a key expired, a service credit paid. Each event is tried up to 7 times and delivery is at least once, so keep the event id.
Last updated:
Events
| Type | Sent when |
|---|---|
balance.low | Sent when:The spendable balance falls to or under the threshold of the low-balance alert; once per crossing, and at most once an hour |
key.cap_warning | Sent when:A key's spend reaches 90% of its cap; once per key |
key.revoked | Sent when:A key is revoked: it reached its spend cap (spend_cap), you revoked it (user), or support did (admin) |
key.expired | Sent when:A key's expiry time passes |
sla.credit_issued | Sent when:A month's service credit is paid to the wallet (service credit): the Jalali month (period, such as 1405-09), the vendor, the credit rate (the one that decided the percentage), the percentage and the amount; once per credit |
affiliate.payout_paid | Sent when:A withdrawal of your cash commission is recorded as paid: the request's id, the amount and the time it was recorded; once per request |
Addresses are registered in the dashboard under Webhooks (/dashboard/webhooks, in Persian); up to 5 per account. An address belongs to a personal account. Nothing is sent for an account that is deactivated or deleted.
The request you receive
{
"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 }
}| Header | Value |
|---|---|
X-1xai-Webhook-Id | Value:The event id; the same on every attempt and equal to the body's id |
X-1xai-Webhook-Event | Value:The event type |
X-1xai-Webhook-Attempt | Value:The attempt number |
X-1xai-Webhook-Timestamp | Value:Unix seconds of this attempt |
X-1xai-Webhook-Signature | Value:v1= followed by the HMAC-SHA256 signature in hex |
Every amount is whole Toman. No event carries a key's secret or hash; key_prefix is the key's display prefix.
Verifying the signature
- Read the raw request body, before any JSON parsing.
- Reject the request when
X-1xai-Webhook-Timestampis more than 300 seconds from your clock. - Compute HMAC-SHA256, keyed with that address's secret (
whsec_…, the whole string), over the timestamp, a dot, and the raw body. - Compare
v1=plus its hex withX-1xai-Webhook-Signature, using a constant-time comparison. - Answer with a
2xxstatus within 10 seconds, and do the work after answering. - Ignore an event id you have already processed.
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)Delivery and retries
- Success is any
2xxanswer. Anything else (another status, a redirect, a timeout, a TLS error) is a failed attempt. - Up to 7 attempts per event and address, at growing intervals; the last attempt is about a day after the first.
- Order between events is not guaranteed, and one event may arrive twice.
- After each failed attempt nothing is sent to that address for a while: 30 seconds after the first failure, doubling with each failure in a row up to an hour. Events wait in the meantime. A delivery that succeeds ends the pause.
- At most 30 sends a minute and 300 an hour per account (test events included). A delivery over that ceiling waits in the queue; it is not dropped.
- Up to 500 deliveries may wait for one account; an event still waiting after 72 hours is not sent.
- An address whose last 20 attempts all failed, the first of them at least 24 hours ago, is switched off and you get one email. You switch it back on from the dashboard; its failure count stays until a delivery succeeds, so an address that fails again is switched off again at its next failure.
- Each delivery's log (every attempt with its time, status and outcome) is in the dashboard and is kept 30 days, and the newest 200 per account. A test event can be sent from there too: at most 5 a minute and 50 a day.
- An address must be
https://, on port443or8443and a public name, without a user name and password; internal and private addresses are refused.
1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.