实时消息同步的核心是回调机制——客户发消息平台通过 Webhook 推到我们的服务服务处理后存库或转发。这篇讲回调机制的细节怎么接、怎么验、怎么保证不丢不重。底层用的是Eyun 平台开放的企微 API回调通过 Webhook 推送首次创建时返回 secret 用于验签。回调接入配 URL 拿 secret在平台配置回调 URL平台会推一条验证请求服务返回指定内容即验证通过。验证通过后平台开始推送事件。app.route(/wx-api/webhook/, methods[POST]) def webhook(): event request.headers.get(X-Eyun-Event) payload request.json return ok回调头X-Eyun-Event标识事件类型X-Eyun-Delivery是投递 ID。消息体字段在开发文档里有完整说明。验签用 secret 校验签名每条回调带签名用首次配置时拿到的 secret 做 HMAC-SHA256 校验。验不过直接返回 403不处理。import hmac, hashlib def verify_signature(secret, body, signature): expected hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)验签是底线跳过等于任何人都能往你的服务推消息。去重delivery_id 防重复回调是至少一次投递同一条消息可能推多次。用 delivery_id 做去重键Redis SET NX 判断24 小时内只处理一次。delivery_id request.headers.get(X-Eyun-Delivery) if not redis.setnx(fcb:{delivery_id}, 1): return ok # 重复跳过 redis.expire(fcb:{delivery_id}, 86400)异步处理先响应再干活回调必须 5 秒内响应处理逻辑不能同步执行。接收层只做验签、去重、落库、推队列立即返回 200。处理线程从队列取消息异步处理。落库保证消息不丢即使服务重启未处理的消息还在数据库里可以重放。事件类型按事件分发不同事件走不同处理逻辑message客户消息走消息处理管道add_external_contact加好友发欢迎语、打标签group_member_add群成员增加发入群欢迎message_read消息已读更新送达状态事件分发表配置化新增事件类型加配置不改代码。回调机制的关键在可靠性回调机制本身不难难在可靠性验签防伪造、去重防重复、异步防超时、落库防丢失。这四点做扎实实时消息同步就稳了。 
长河君 · 2026/10/14 6:25:42 · 阅读 1.2k 企业微信API接口实战：如何通过回调机制实现实时消息同步
实时消息同步的核心是回调机制——客户发消息平台通过 Webhook 推到我们的服务服务处理后存库或转发。这篇讲回调机制的细节怎么接、怎么验、怎么保证不丢不重。底层用的是Eyun 平台开放的企微 API回调通过 Webhook 推送首次创建时返回 secret 用于验签。回调接入配 URL 拿 secret在平台配置回调 URL平台会推一条验证请求服务返回指定内容即验证通过。验证通过后平台开始推送事件。app.route(/wx-api/webhook/, methods[POST]) def webhook(): event request.headers.get(X-Eyun-Event) payload request.json return ok回调头X-Eyun-Event标识事件类型X-Eyun-Delivery是投递 ID。消息体字段在开发文档里有完整说明。验签用 secret 校验签名每条回调带签名用首次配置时拿到的 secret 做 HMAC-SHA256 校验。验不过直接返回 403不处理。import hmac, hashlib def verify_signature(secret, body, signature): expected hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)验签是底线跳过等于任何人都能往你的服务推消息。去重delivery_id 防重复回调是至少一次投递同一条消息可能推多次。用 delivery_id 做去重键Redis SET NX 判断24 小时内只处理一次。delivery_id request.headers.get(X-Eyun-Delivery) if not redis.setnx(fcb:{delivery_id}, 1): return ok # 重复跳过 redis.expire(fcb:{delivery_id}, 86400)异步处理先响应再干活回调必须 5 秒内响应处理逻辑不能同步执行。接收层只做验签、去重、落库、推队列立即返回 200。处理线程从队列取消息异步处理。落库保证消息不丢即使服务重启未处理的消息还在数据库里可以重放。事件类型按事件分发不同事件走不同处理逻辑message客户消息走消息处理管道add_external_contact加好友发欢迎语、打标签group_member_add群成员增加发入群欢迎message_read消息已读更新送达状态事件分发表配置化新增事件类型加配置不改代码。回调机制的关键在可靠性回调机制本身不难难在可靠性验签防伪造、去重防重复、异步防超时、落库防丢失。这四点做扎实实时消息同步就稳了。