公众号发文 Webhook 接入指南
把公众号新文章送进你的程序或自动化工具。先连通接收端,再按需要加正文。
更新:2026-11-11 · 曼格云 API先分清:管理 API 与通知 Webhook
管理 API 由你主动调用,用来查询套餐、购买订阅、配置渠道和查询动态。Webhook 则由曼格云在发现新文章后,向你配置的接收地址主动发送 JSON。两者使用不同方向的请求,也不应混用鉴权密钥。
管理入口为 POST /openapi/wechat-publication-alerts-api/monitor,使用平台 X-API-Key 鉴权。先发送 {"action":"options"} 获取当前套餐与费用,再按应用内最新文档执行其他操作。购买订阅需要稳定的 Idempotency-Key,防止重复扣费。
配置一个 Webhook 通知渠道
- 进入发文提醒应用的「通知渠道」,新增 Webhook。
- 填写公网 HTTP 或 HTTPS 接收地址,支持域名、IP 和自定义端口(1–65535)。HTTP 明文传输,建议可用时使用 HTTPS。地址不能重定向到其他位置。
- 选择自定义请求头,按接收端要求填写鉴权信息。
- 先发送测试,确认接收成功后保存,并把渠道关联到公众号订阅。
Content-Type: application/json
Authorization: Bearer YOUR_WEBHOOK_TOKEN
X-Publication-Event-ID: example-delivery-id
X-Publication-Timestamp: <Unix 秒级时间戳>普通 Bearer 密钥按原值发送,无需二次加密、哈希或生成签名。你的接收端负责校验该密钥。平台也提供可选 HMAC 模式;选用时再按应用内文档校验签名。
使用管理 API 时,选择 webhookAuthMode="headers",并配置 customHeaders={"Authorization":"Bearer YOUR_WEBHOOK_TOKEN"}。接收密钥是占位符,请自行替换,不要把平台 API Key 当作回调密钥随意发送。
收到的数据是什么样
每次 Webhook 对应一个发文事件。下方为开启 text 正文的结构示例,字段值仅作演示。发送测试时正文状态为 test,正式获取成功为 ready。
{
"id": "example-delivery-id",
"type": "wechat.publication.detected",
"coverage": "ordinary_article_window",
"event": {
"id": "example-event-id",
"subscriptionId": "example-subscription-id",
"biz": "PUBLIC_ACCOUNT_BIZ",
"accountName": "示例公众号",
"group": {
"id": "article:2247481234:1",
"title": "示例文章标题",
"url": "https://mp.weixin.qq.com/s/EXAMPLE_ARTICLE",
"contentType": "article",
"totalCount": 1,
"groupAt": "2026-11-09T02:00:00Z"
},
"digest": "",
"digestStatus": "disabled",
"digestChargeMicros": 0,
"read": false,
"createdAt": "2026-11-09T02:02:00Z"
},
"articleContent": {
"status": "ready",
"format": "text",
"chargeMicros": 0,
"callId": "example-content-call-id",
"data": {
"article": {
"title": "示例文章标题",
"ipLocation": "广东"
},
"format": "text",
"content": "示例正文,仅用于说明字段结构。"
}
}
}| 字段 | 含义 |
|---|---|
id | 本次投递的稳定 ID,用于接收端去重。同一文章发给不同渠道时,投递 ID 不同。 |
event.accountName | 公众号展示名称。 |
event.group | 文章标题、公开链接、文章身份与发布时间;时间为 RFC 3339,Z 表示 UTC。 |
event.digest | 可选摘要,未开启、处理中或没有摘要时可能为空。 |
articleContent | 只有开启正文的 Webhook 才出现。关闭时整个字段省略。 |
articleContent.status | ready 成功、failed 失败、expired 暂存过期、test 测试示例。 |
articleContent.chargeMicros | 该次正文调用的实际净费用,1,000,000 微元 = 1 元。 |
选择适合你的正文格式
| 格式 | 用途 |
|---|---|
| text | 纯文本,适合检索、保存和后续整理。 |
| body_html | 正文 HTML 片段,适合嵌入自己的展示页。 |
| full_html | 完整页面 HTML 文档。 |
| html | 正文接口的兼容 HTML 格式,规则以正文文档为准。 |
| media | 媒体清单,不是全文。 |
| analysis | 文章统计结果,不是全文。 |
余额不足、Key 失效或正文获取失败时,仍发送基础提醒并带上错误状态;收到提醒不代表正文获取成功。
正文只在回调中返回。队列加密暂存约 24 小时供重投,投递记录不是永久正文库;接收后请及时保存。过期后返回提醒及 expired 状态。
接收成功后返回 2xx,并按投递 ID 去重
可靠保存事件后尽快返回 HTTP 200 或 204,后续处理放到自己的异步流程。任意 2xx 都视为本次通知成功,不要求固定 JSON 响应。
接收端按顶层 id 去重。正文状态与通知状态分开判断;若需要合并多个渠道的同一篇文章,可以结合 event.biz 与 event.group.id 识别文章。
测试失败时,直接看接收端返回了什么
测试结果会展示接收端 HTTP 状态码和响应正文;响应限长并对敏感信息脱敏。如果没有收到 HTTP 响应,则检查 DNS、证书和连接错误。
- 401 / 403:核对请求头名称、Bearer 前缀和密钥值。
- 404:核对完整 Webhook 路径,以及接收端是否已启用。
- 400 / 422:根据响应正文核对接收端字段要求;Webhook 顶层不是文章对象,而是投递信封。
- 正文为空:检查 includeContent、所选格式和 articleContent.status;media / analysis 本来就不是正文字符串。
正式通知对 429 有限重试,其他非 2xx 标为失败;超时等结果不明时不会自动重发。先核对接收端处理结果,再在投递记录里确认重复风险并手动重试。
可以把这个页面交给协助你配置的 AI 或开发者。先连接一个测试工作流,确认字段映射,再启用正式业务。
关心的公众号,
现在就关注起来。
准备一篇目标公众号的文章链接,进入应用配置监控。