Webhook 事件推送

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

支持的事件类型

事件类型	触发时机
guest.created	嘉宾创建成功
guest.updated	嘉宾信息更新
guest.card_created	通过卡片创建嘉宾成功（异步任务完成）
match.created	匹配记录创建
match.status_changed	匹配状态变更
membership.created	会员开通
membership.expired	会员过期
activity.created	活动创建
activity.registered	活动报名
work_wechat.created	工作微信号创建
work_wechat.updated	工作微信号信息更新
work_wechat.associated	工作微信号关联红娘/公司/代理
work_wechat.disassociated	工作微信号解绑红娘/公司/代理
work_wechat.transferred	工作微信号关联转移或管理员转移
work_wechat.status_changed	工作微信号启用/停用
work_wechat.deleted	工作微信号删除
work_group.created	微信群创建
work_group.updated	微信群信息更新
work_group.associated	微信群关联红娘/工作微信号
work_group.disassociated	微信群解绑红娘/工作微信号
work_group.status_changed	微信群启用/停用
work_group.deleted	微信群删除

推送格式

平台会向你配置的 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"
    }
}

验证推送来源

每个 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)

注意事项

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