企业微信API：Webhook回调开发

梦想的旅途22026-08-28 15:04

1. 引言

只调发送接口，做出来的是通知器。搜「企业微信Webhook」「企业微信消息回调」「企微进群事件」的人，要的是客户在企微上的动作实时进系统。

2. 企微回调常见事件

客户文本 / 图片 / 文件消息
好友申请、通过
客户入群、退群
设备掉线、登录状态

接收侧对接 QIWe API。网关把回调 payload 转成内部统一事件，解析逻辑按事件类型分发，不要堆在一个 if-else 里。

3. 最小规范

公网可达、验签、快速 200、消息 ID 幂等、消费者可重入。

python 复制代码

@app.post("/cb/qiwe")
def cb():
    data = request.get_json(force=True)
    if not verify(request):
        return "invalid", 403
    event_id = extract_id(data)
    if redis.setnx(f"qiwe:evt:{event_id}", 1):
        redis.expire(f"qiwe:evt:{event_id}", 86400)
        queue.publish("qiwe.events", data)
    return "ok"

4. 分发

消息 → 会话/自动回复；好友 → 客户档案/打标签；入群 → 欢迎语；掉线 → 运维告警与重连。

配置回调、查看字段和调试，以 QiWe API文档（https://doc.qiweapi.com/）为准。先打原始 JSON 日志再写解析，能少踩一半字段坑。

5. 调试

同一报文重放三次只处理一次；接口超时是否重推；掉线恢复后是否误补发欢迎语。

6. 安全

回调 URL 不暴露前端；QIWe API Token 只放服务端，不要写进前端或 Git。

7. 总结

企业微信 Webhook 是 SCRM 和智能客服的中枢。企微收事件不稳，工作台会话列表就会假死。