所有文档

Webhooks

1024X 通过 HTTPS POST 发送 JSON 事件, 用 webhook 监听订阅与用量变化, 不用再轮询。

配置接收地址

在 /user/settings → Webhooks 里添加一个 HTTPS URL。发送失败会指数退避重试, 持续最长 24 小时。

事件类型

事件触发时机
usage.threshold_exceeded日 / 月 token 配额阈值触发。
key.created账户新建了一把 API Key。
key.revokedKey 被删除或自动撤销。
subscription.activated一次 Stripe 结账完成, 套餐已生效。
subscription.renewed续费账单支付完成, 周期已延长。
subscription.cancelled用户取消订阅, 当前周期到期前仍生效。

事件负载

json
{
  "id": "evt_01ABC...",
  "type": "subscription.activated",
  "created_at": "2026-05-06T08:42:11Z",
  "data": {
    "user_id": "1",
    "plan_code": "PRO",
    "stripe_subscription_id": "sub_xxx",
    "period_start": "2026-05-06T08:42:00Z",
    "period_end":   "2026-06-06T08:42:00Z"
  }
}

验证签名

每次请求都带 x-1024x-signature 头, 它是 raw body 用 endpoint secret 做的 HMAC-SHA256。落地业务前务必先验签。

ts
import crypto from 'node:crypto';

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

幂等

每个事件有唯一的 id。重试会复用同一个 id, 业务侧请按 id 去重再处理副作用。