开发者文档

能推送什么

事件 key	触发时机
user.registered	新用户注册（含来源归因）
post.created	新帖发布（含草稿定时发布）
report.created	新举报
feedback.created	新意见反馈
draft.publish_failed	定时发布失败
member.activated	会员开通 / 续费（兑换码、Stripe、X币）

订阅时可以选择「全部事件」，也可以只勾选其中几个，避免高频事件刷屏。

配置方式

由站长在后台 /admin/webhooks 添加渠道：

渠道	需要提供	备注
飞书群机器人	Webhook 地址（可选签名密钥）	开了「签名校验」时必须填密钥，否则收不到消息
企业微信群机器人	Webhook 地址（key 已含在地址里）	官方限流较严，建议只订阅关键事件
Discord	Webhook URL	429 会带 retry_after，我们会遵守
自定义 HTTP	https 地址（可选签名密钥）	我们会 POST 统一 JSON，并加签名头

配置后可以点「发送测试」立刻验证；后台也会展示最近投递记录与失败原因。

自定义端点的报文格式

{
  "event": "post.created",
  "title": "新帖：标题",
  "text": "【X2Post】新帖：标题\n版块【开放讨论】· 作者 moatkon\nhttps://x2post.com/posts/11",
  "summary": "版块【开放讨论】· 作者 moatkon",
  "url": "https://x2post.com/posts/11",
  "timestamp": "2026-09-22T00:00:00Z",
  "data": { "postId": 11, "title": "标题", "author": "moatkon", "category": "开放讨论" }
}

如果配置了签名密钥，请求会带两个头：

X-X2Post-Signature: sha256=<hex>
X-X2Post-Timestamp: <unix 秒>

签名算法：HMAC-SHA256(secret, 原始请求体) 的十六进制（小写）。校验示例：

const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody)          // 必须用原始字符串，不要先 JSON.parse 再 stringify
  .digest('hex');
if (rawBody && expected !== req.headers['x-x2post-signature']) return res.status(401).end();

投递与重试

• 事件与业务同事务入队：业务成功则一定有投递记录，业务回滚则一起回滚；
• 失败按 1 / 5 / 30 / 120 / 720 分钟退避重试，最多 6 次；
• 连续 5 次「重试耗尽」会自动停用该渠道，并给配置人发一条站内通知；
• 后台可以手动重投单条投递记录；
• 请让你的端点快速返回 2xx（超过 5 秒会按失败处理），重活放到自己的队列里做。

安全建议

• 机器人地址本身即密码，后台只显示打码后的尾部，请勿外传；
• 自定义端点请校验签名与时间戳，避免被伪造请求；
• 站点只允许 https 目标，并拒绝内网/本机地址（防 SSRF）。