Webhook 事件推送

如果你的系统需要实时感知数据变更（而非轮询），可以向管理员申请开通 Webhook 推送。

6.1 支持的事件类型

事件类型	触发时机
guest.created	嘉宾创建成功
guest.updated	嘉宾信息更新
guest.card_created	通过卡片创建嘉宾成功（异步任务完成）
match.created	匹配记录创建
match.status_changed	匹配状态变更
membership.created	会员开通
membership.expired	会员过期
activity.created	活动创建
activity.registered	活动报名

6.2 推送格式

平台会向你配置的 webhook_url 发送 HTTP POST 请求：

{
    "event": "guest.created",
    "timestamp": 1722844800,
    "data": {
        "id": 1002,
        "name": "李四",
        "gender": "female",
        "company_id": 3,
        "created_at": "2025-08-05 10:00:00"
    }
}

6.3 验证推送来源

每个 Webhook 请求都携带 X-Webhook-Signature 头，使用 HMAC-SHA256 签名。接收方使用分配的 webhook_secret 验证：

import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature: str, webhook_secret: str) -> bool:
    expected = hmac.digest(
        webhook_secret.encode("utf-8"),
        payload_bytes,
        "sha256"
    ).hex()
    return hmac.compare_digest(expected, signature)

6.4 注意事项

• 推送失败会自动重试 3 次（间隔 30s → 2min → 10min，递增退避）
• 你的接收端应尽快返回 2xx 响应，避免超时
• 连续失败 10 次后 Webhook 会被自动禁用，需联系管理员重新启用