callback_url 怎么用

一句话结论

callback_url 是你侧的一个公网可达 HTTPS 端点，颜小二自媒体发布 API 平台会在每条发布任务完成（或失败）后，主动把结构化结果 POST 给这个端点——你不需要轮询，签名校验通过、入库、按 external_id 找回上下文即可。

背景：为什么要用回调

发布任务是异步的：你调一次统一文章接收 API，平台层把任务下放给本地 Agent 去执行——执行时长从几秒到几分钟不等（取决于平台限频、登录态、网络）。如果让你每秒轮询查任务状态，两侧都浪费 CPU 和带宽。

固定 callback_url 把"等结果"变成"被通知"：

• 你侧：注册一个固定回调端点，等通知就行
• 颜小二侧：任务完成后主动 POST，结构化字段 success / failed / login_expired

详细解答：分 5 步讲清楚

步骤 1：在你的服务里准备一个 HTTPS 端点

最简化形式（伪代码）：

```python @app.post("/yxe/callback") def yxe_callback(req): body = req.json()

1. 校验签名（避免伪造）

if not verify_signature(req.headers, body): return 401

2. 按 external_id 找你侧业务上下文

article = find_article(body["external_id"])

3. 处理状态

if body["status"] == "success": save_publish_result(article, body) elif body["status"] == "failed": notify_human_review(article, body["error_msg"]) elif body["status"] == "login_expired": trigger_relogin(body["account_id"])

4. 必须在 5 秒内返回 200

return 200 ```

步骤 2：在颜小二后台 / 接入时配置 callback_url

每个租户独立 callback_url、独立签名密钥。一个租户内可以有多个 group_code，但通常一个租户一个回调端点足够。

步骤 3：理解回调字段结构

颜小二回调的核心字段大致包含：

| 字段 | 含义 | |---|---| | external_id | 你提交时的外部 ID，用于幂等与定位 | | group_code | 当时指定的账号分组 | | account_id | 实际执行该任务的账号 | | platform | 平台名（toutiao / wechat_mp / baijiahao / zhihu 等） | | status | success / failed / login_expired | | platform_url | 成功时的发布链接 | | platform_id | 平台侧文章 ID | | error_msg | 失败时的结构化原因 | | retryable | 是否可重试 | | timestamp | 回调时间戳 |

具体字段以 [API 文档](/docs.html) 为准。

步骤 4：处理签名与时间戳

签名校验防伪造，时间戳防重放。建议：

• 时间戳与服务器时差 ≤ 5 分钟
• 签名算法（如 HMAC-SHA256）按 [API 文档](/docs.html) 实现
• 签名校验失败直接返回 401，不要返回 200

步骤 5：处理回调幂等

颜小二在网络抖动或 5xx 时会重试投递。你侧必须按 "external_id + platform + status" 做幂等去重，避免同一结果入库两次。

注意事项：4 个常见坑

坑 1：callback_url 返回慢或挂掉

颜小二期望 5 秒内拿到 200。如果你侧处理逻辑重，应该先入队再返回 200，不要在回调里同步做大量计算。

坑 2：HTTPS 证书问题

颜小二只投递到 HTTPS 端点。证书过期、自签名、TLS 版本过低都会导致投递失败。建议用 Let's Encrypt 或商业证书。

坑 3：未做签名校验

不做签名校验意味着任何人可以伪造回调让你脏数据。必须做签名校验。

坑 4：忽略 login_expired

login_expired 不是普通失败，是登录态失效信号。收到后应触发该账号的本地 Agent 重登流程，否则后续所有任务都失败。

重试与失败兜底

颜小二的重试策略大致是：

| 类型 | 重试 | |---|---| | 你侧 callback 返回 5xx | 自动重试，指数退避 | | 你侧 callback 返回 4xx | 不重试，进死信 | | 你侧 callback 超时 | 自动重试 | | 你侧 callback 返回 200 | 不重试 |

如果你的端点长时间不可达，颜小二会把回调推入死信队列，可在后台手动重试。

注意事项决策树

`` 收到回调 → 校验签名 ├ 失败 → 返回 401，告警 └ 成功 └ 解析 status ├ success → 入库 platform_url + platform_id ├ failed → 看 retryable，true 则等下次自动重发，false 转人工 └ login_expired → 触发该账号本地 Agent 重登 ``

相关问题

• [颜小二是什么？和编辑器有什么区别](/faq.html)
• [多租户隔离怎么实现](/faq.html)
• [登录态保存在哪里安全吗](/faq.html)
• [失败任务怎么自动重试](/faq.html)
• [callback 详细工作机制](/lp/faq-how-callback-works.html)

常见问题（FAQ）

Q：callback_url 必须是公网吗？ SaaS 形态下需要公网 HTTPS 可达。私有部署形态支持私网 callback。

Q：每个 group_code 可以有不同的 callback_url 吗？ 默认一个租户一个 callback_url。需要分组级别隔离的场景[联系商务](/contact.html#form)定制。

Q：颜小二的回调有保证投递（at-least-once）吗？ 有，至少一次投递，所以你侧必须做幂等处理。

Q：callback 失败之后死信队列保留多久？ 默认有保留期，期间可在后台手动重试。具体时长见[API 文档](/docs.html)。

Q：如果我侧暂时下线，已经发出去的任务怎么办？ 任务在颜小二侧不变，回调进死信队列等你恢复后手动重试或自动恢复。

下一步

把上面伪代码改成你自己的语言，跑通最小可行回调端点（含签名校验 + 状态处理）。这一步通常 0.5-1 人天。

→ [查看 API 文档](/docs.html) | [callback 工作机制详解](/lp/faq-how-callback-works.html) | [更多常见问题](/faq.html) | [咨询商务 / 申请试用](/contact.html#form)