订阅 Webhook#

#投递格式

Halo 以 POST 请求把事件投递到接入方配置的回调 URL，请求体是统一信封：

{
  "eventType": "SUBSCRIPTION_CREATED",
  "timestamp": "2026-09-17T10:00:00Z",
  "webhookId": 1,
  "data": {
    "subscription": {}
  }
}

请求头：

#验证签名

使用创建 Webhook 时填写的密钥，对未经解析的原始请求体验签，并使用常量时间比较：

import hashlib
import hmac

expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(received_signature, expected):
    raise ValueError("invalid webhook signature")

#返回状态与重试

Halo 等待响应的超时时间为 10 秒。请先完成验签与持久化，尽快返回 2xx，耗时处理放到后台任务。投递失败后可以在控制台的投递记录中查看请求与响应，并手动重新投递。

#幂等与顺序

• 采用至少一次投递：自动重试与手动重投都可能产生重复请求。请以 X-Halo-Webhook-Id 作为幂等键，处理过的 ID 直接返回 2xx。
• 同一订单（或同一订阅）的事件通常按发布顺序投递，但重试不受顺序约束，可能出现交错。请以订阅的当前快照收敛本地状态，不要假设事件严格有序。
• 同一逻辑事件的多次投递共享同一个 X-Halo-Webhook-Id；手动重新投递时 X-Halo-Delivery-Attempt 会重置为 1。

#订阅事件参考

#载荷字段

所有订阅事件的 data.subscription 结构一致，是事件发生之后的订阅快照，不包含订单号与变更前后明细：

需要订单号、差价明细或变更前后的周期时，请用 Console 查询接口补全：续费单、转正单与变更单本身也是订单，会同时触发订单域事件。

#关联的订单事件

订阅的续费单、转正单与变更单都是普通订单，因此还会触发订单域 Webhook：

• ORDER_CREATED：订单创建。
• ORDER_PAID：订单支付完成。应付金额为 0 的订单在创建时即视为已支付，会同时触发 ORDER_CREATED 与 ORDER_PAID。
• FULFILLMENT_REQUESTED：需要接入方交付订阅行时的交付请求，见履约回调。

订单载荷中的 data.order.items[].subscriptionMetadata 可以区分订单来源：

#处理建议

1. 验签 → 用 X-Halo-Webhook-Id 去重 → 用 data.subscription 覆盖本地快照 → 按新的 status 与 entitlements 调整限额。
2. 开通与关闭权益必须幂等，重复投递不得叠加额度。
3. 以 Halo 下发的快照为准，不要在本地自行推算周期，详见权益如何判定。
4. 控制台的发送测试事件会投递 WEBHOOK_TEST，载荷是订单结构且字段与真实事件不完全一致（例如收货地址使用的是测试字段），请勿写入业务数据。