接收事件推送
订单支付、会员卡开卡、签到等业务发生后,Betly 会向应用的回调地址发送 HTTPS 请求。应用不用轮询,就能及时同步状态、触发自己的流程。
订阅事件
入口:应用详情 →【事件订阅】
- 填写【回调路径】,相对应用地址,例如
/hooks/betly。 - 勾选【事件类型】。只能勾选应用权限范围覆盖的事件,例如没有
orders:read就不能订阅订单事件。 - 保存后即开始推送。每次推送的结果可以在【投递记录】查看,失败的可以单条或批量重放。
回调路径必须不需要登录就能访问,且直接返回结果,不要重定向(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去重;对状态敏感的逻辑,收到事件后再调接口取最新状态,不要只依赖事件到达的先后。
