Skip to content

接收事件推送 ​

订单支付、会员卡开卡、签到等业务发生后,Betly 会向应用的回调地址发送 HTTPS 请求。应用不用轮询,就能及时同步状态、触发自己的流程。

订阅事件 ​

入口:应用详情 →【事件订阅】

  1. 填写【回调路径】,相对应用地址,例如 /hooks/betly。
  2. 勾选【事件类型】。只能勾选应用权限范围覆盖的事件,例如没有 orders:read 就不能订阅订单事件。
  3. 保存后即开始推送。每次推送的结果可以在【投递记录】查看,失败的可以单条或批量重放。

回调路径必须不需要登录就能访问,且直接返回结果,不要重定向(3xx 按失败处理)。

事件类型 ​

事件含义需要的权限范围
order.paid、order.cancelled订单已支付、已取消orders:read
order_item.refunded订单项已退款orders:read
employee.joined、employee.left、employee.roles_changed员工入职、离职、角色变更employees:read
user_card.issued、user_card.activated会员卡发放、开卡cards:read
user_card.paused、user_card.resumed会员卡暂停、恢复cards:read
user_card.expired、user_card.used_up会员卡到期、用完cards:read
check_in.created、check_in.revoked签到、撤销签到checkins:read
schedule.cancelled、schedule.ended排期取消、结束schedules:read
booking.created、booking.cancelled、booking.checked_in约课、取消约课、约课签到bookings:read

请求格式 ​

http
POST /hooks/betly HTTP/1.1
Content-Type: application/json
User-Agent: Betly-Hooks/1.0
Betly-Event-Id: 5c0e0a52-…
Betly-Event-Type: order.paid
Betly-Delivery-Attempt: 1
Betly-Signature: t=1791428400,v1=9f2c…

{
  "id": "5c0e0a52-…",
  "type": "order.paid",
  "schema_version": 1,
  "org_id": "761b34b5-…",
  "occurred_at": "2026-10-08T20:00:03+08:00",
  "data": { "order_id": "a1f3…", "store_id": "e04b…", "amount": "1280.00", "status": "paid" }
}

data 只包含编号、状态、金额、门店和时间,不包含手机号、证件号等个人信息。需要更多字段时,用应用凭证调接口查询。

校验签名 ​

Betly-Signature 中的 v1 是用 Webhook 密钥对“t + 英文句点 + 原始请求体”做 HMAC-SHA256 的十六进制结果。密钥用完整字符串,包括 whsec_ 前缀。

js
import crypto from 'node:crypto';

/** rawBody 必须是收到的原始字符串,不要先 JSON.parse 再序列化 */
export function verifyBetlySignature(rawBody, signatureHeader, secret, now = Date.now()) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.trim().split('=', 2))
  );
  const timestamp = Number(parts.t);
  if (!parts.v1 || !Number.isFinite(timestamp)) return false;
  if (Math.abs(now / 1000 - timestamp) > 300) return false; // 超过 5 分钟视为重放
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest();
  const actual = Buffer.from(parts.v1, 'hex');
  return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
}

签名不通过时返回 401,不要处理事件内容。

响应与重试 ​

  • 5 秒内返回 2xx 视为成功。耗时的处理请先入队,再立即返回。
  • 失败(超时、非 2xx、网络错误)会自动重试,最多 7 次,间隔约为立即、1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时。
  • 连续失败超过 24 小时,订阅会被暂停,并通知场馆管理员;修复后由管理员在【事件订阅】里重新启用,再在【投递记录】里重放漏收的事件。
  • 推送至少一次、不保证顺序:同一事件可能收到多次,请按 Betly-Event-Id 去重;对状态敏感的逻辑,收到事件后再调接口取最新状态,不要只依赖事件到达的先后。

相关操作 ​