集成向导鉴权端点约定模型错误Webhook
1tokens1tokens
开始使用API 参考

Webhook

1tokens 会在平台内发生事件时，向你在控制台登记的 HTTPS 地址发送带签名的 POST 请求。在控制台「Webhook」页新建端点、勾选要订阅的事件即可，新端点最迟 30 秒内生效。

事件目录

模型

类型名称data 字段
model.listed模型上架model tenant_id previous_status status actor
model.delisted模型下架model tenant_id previous_status status actor
model.deprecated模型弃用model previous_status status actor
model.price.changed售价变动model tenant_id pricing_status sale_price_mode multiplier price changes actor
model.user_price.changed专属价变动model user_id multiplier changes actor
model.updated模型更新model changes actor

API Key

类型名称data 字段
api_key.createdKey 创建api_key actor
api_key.updatedKey 修改api_key changes actor
api_key.revokedKey 吊销api_key previous_status status actor
api_key.expiredKey 过期api_key actor
api_key.quota.exhausted额度用尽api_key quota_limit_usd consumed_usd actor
api_key.rate_window.exceeded时间窗超限api_key window limit_usd consumed_usd actor

账户

类型名称data 字段
account.balance.low余额不足account threshold_usd request_id actor
account.balance.exhausted余额耗尽account reason request_id actor
account.credit.topup到账account amount_usd amount_credits source order_no actor
account.credit.adjusted调额account delta_usd delta_credits kind reason actor
account.trial.granted试用发放account amount_credits actor
account.disabled账号停用account previous_status status actor
account.enabled账号恢复account previous_status status actor
account.password.reset密码重置account actor

订单

类型名称data 字段
order.created订单创建order actor
order.paid支付成功order paid_at previous_status status actor
order.failed支付失败order reason previous_status status actor
order.redeemed兑换成功order code_masked actor

订阅

类型名称data 字段
subscription.started订阅开通subscription previous_status status actor
subscription.renewed订阅续费subscription actor
subscription.upgraded订阅升级subscription changes actor
subscription.cancelled订阅取消subscription previous_status status actor
subscription.payment_failed续费失败subscription reason actor
subscription.quota.exhausted配额用尽subscription request_id actor

任务

类型名称data 字段
task.video.succeeded视频完成task video_count actor
task.video.failed视频失败task actor
task.generation.succeeded生成完成task media output_count actor
task.generation.failed生成失败task media actor

公告

类型名称data 字段
content.changelog.published更新日志发布entry actor
content.article.published文章发布article tenant_id previous_status status actor
content.article.unpublished文章下架article tenant_id previous_status status actor

Webhook

类型名称data 字段
webhook.endpoint.auto_disabled端点被停用endpoint reason consecutive_failures actor

推送格式

所有事件共用同一个信封：id 事件唯一 id、type 事件类型、domain 功能域、created_at 发生时间（ISO 8601 UTC）、api_version 版本、data 事件内容。data 里键名一律 snake_case，时间以 _at 结尾，金额是十进制字符串（_usd / _credits），没有值的字段显式为 null。同一事件可能因重试重复送达，请按 id 做幂等。

{  "id": "evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8B",  "type": "model.price.changed",  "domain": "model",  "created_at": "2026-11-04T08:12:33Z",  "api_version": "2026-11-04",  "data": { }}

请求头

POST https://your-server.example/webhooksContent-Type: application/jsonUser-Agent: Webhooks/1.0X-Event-Id: evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8BX-Event-Type: model.price.changedX-Delivery-Id: 123456X-Timestamp: 1762243953X-Signature: v1=5f1c…

验证签名

用创建端点时保存的密钥，对「X-Timestamp 的值 + 英文句点 + 原始请求体字节」计算 HMAC-SHA256，与 X-Signature 里 v1= 后面的十六进制做常量时间比较；时间戳与当前时间相差超过 5 分钟应拒收。先回 2xx 再处理业务，整个响应需在 10 秒内完成。

import { createHmac, timingSafeEqual } from "node:crypto";export function verify(secret, headers, rawBody) {  const ts = headers["x-timestamp"];  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;  const expected = createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");  const given = String(headers["x-signature"]).replace(/^v1=/, "");  return given.length === expected.length && timingSafeEqual(Buffer.from(given, "hex"), Buffer.from(expected, "hex"));}
import hmac, hashlib, timedef verify(secret: str, headers: dict, raw_body: bytes) -> bool:    ts = headers["X-Timestamp"]    if abs(time.time() - int(ts)) > 300:        return False    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()    given = headers["X-Signature"].removeprefix("v1=")    return hmac.compare_digest(given, expected)
func verify(secret string, ts, sig string, body []byte) bool {	t, _ := strconv.ParseInt(ts, 10, 64)	if math.Abs(float64(time.Now().Unix()-t)) > 300 {		return false	}	mac := hmac.New(sha256.New, []byte(secret))	mac.Write([]byte(ts + "."))	mac.Write(body)	expected := hex.EncodeToString(mac.Sum(nil))	return hmac.Equal([]byte(strings.TrimPrefix(sig, "v1=")), []byte(expected))}

重试与自动停用

非 2xx 响应或 10 秒内未响应都算失败，最多尝试 7 次，间隔如下表。全部失败后该条投递标记为耗尽；同一端点连续 10 条投递耗尽会被自动停用并邮件通知，修复后可在控制台重新启用。任一条投递都可在控制台手动重发。

第 N 次尝试距上一次
10
21 min
35 min
430 min
52 h
66 h
724 h

接收地址要求

必须是公网可达的 HTTPS 地址；解析到内网、回环、链路本地等地址的域名会被拒绝。不跟随重定向，响应正文最多读取 64 KB。

错误

Previous Page

On this page

事件目录模型API Key账户订单订阅任务公告Webhook推送格式请求头验证签名重试与自动停用接收地址要求
{
  "id": "evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8B",
  "type": "model.price.changed",
  "domain": "model",
  "created_at": "2026-11-04T08:12:33Z",
  "api_version": "2026-11-04",
  "data": { }
}
POST https://your-server.example/webhooks
Content-Type: application/json
User-Agent: Webhooks/1.0
X-Event-Id: evt_01JBXK6Q3N7Y8R2V4W5X6Z7A8B
X-Event-Type: model.price.changed
X-Delivery-Id: 123456
X-Timestamp: 1762243953
X-Signature: v1=5f1c…
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, headers, rawBody) {
  const ts = headers["x-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const given = String(headers["x-signature"]).replace(/^v1=/, "");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given, "hex"), Buffer.from(expected, "hex"));
}
import hmac, hashlib, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers["X-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    given = headers["X-Signature"].removeprefix("v1=")
    return hmac.compare_digest(given, expected)
func verify(secret string, ts, sig string, body []byte) bool {
	t, _ := strconv.ParseInt(ts, 10, 64)
	if math.Abs(float64(time.Now().Unix()-t)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(strings.TrimPrefix(sig, "v1=")), []byte(expected))
}