Webhook 集成

Webhook 让平台在事件发生时主动推送 JSON 到你的 HTTPS 回调地址，比轮询更实时且省配额。

支持的事件

Event	说明
resource.published	资源发布
resource.updated	资源更新
resource.deleted	资源删除
server.status.online	服务器上线
server.status.offline	服务器下线
post.published	帖子发布
post.deleted	帖子删除

注册 Webhook

进入 Webhook 管理 页面：

• URL（仅 HTTPS）
• 订阅的事件列表
• 自动生成的 32 位签名密钥
• 单应用最多注册 5 个 Webhook

投递请求

平台向你的 URL 发送 POST 请求：

POST /your-callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Webhook-Event: resource.published
X-Webhook-Signature: <hex>
X-Webhook-Timestamp: 1735000000000

{
  "event": "resource.published",
  "data": { "postId": 12345, "title": "...", "..." }
}

验证签名

expected = HMAC_SHA256( secret, X-Webhook-Timestamp + "\n" + raw_body ).hex()
if !constantTimeEquals(expected, X-Webhook-Signature): reject

伪代码（Node.js）：

import crypto from 'crypto'

function verify(req, secret) {
  const ts = req.headers['x-webhook-timestamp']
  const sig = req.headers['x-webhook-signature']
  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}\n${req.rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
}

你的服务必须

• 在 10 秒内返回 2xx（默认超时 10s）
• 处理重复投递（幂等）— 平台至少投递一次，可能重投
• 即使消息有误也尽量 200 回（在你的业务层 ack）

投递失败

非 2xx 或超时会自动进入重试队列：

• 最多 3 次（可配置）
• 指数退避：1min → 5min → 15min
• 最终失败可在 投递历史 看到完整请求/响应快照
• 失败的投递支持手动「重放」（同 payload 重新发送一次）

暂停 / 停用

如下游临时故障，可在 Webhook 管理页把状态切到 PAUSED。期间事件不会进入投递队列。

调试技巧

• 用 webhook.site / ngrok 在本地测试
• 用 Webhook 管理页的「发送测试 ping」验证连通性
• 接到事件后先打日志再处理，方便回溯

收不到推送？逐项排查

• 回调必须是公网可达的 HTTPS：本地开发用 ngrok / webhook.site 暴露临时地址。
• Webhook 状态不是 PAUSED：暂停期间事件不会进入投递队列。
• 事件类型已订阅：只会推送你勾选的事件，确认目标事件在订阅列表里。
• 回调要快：默认 10 秒超时，超时会被判为失败并进入重试；耗时逻辑请先 2xx ACK 再异步处理。
• 去 投递历史 看快照：每次投递的请求头 / 请求体 / 你的响应都有记录，失败可「重放」。
• 验签失败别静默丢弃：先确认用的是 Webhook 自己的签名密钥（与应用 Secret Key 不同），拼接串为 X-Webhook-Timestamp + "\n" + 原始 body。

详细字段定义见 API Reference 里 webhook 部分。