Webhook 与消息嵌入内容

什么时候使用 Webhook

构建通知、外部服务事件或更新可以使用 Webhook。它会向预先选定的文字频道发布消息。若要读取消息、处理命令和按钮或响应事件，请使用机器人。

创建 Webhook

打开文字频道的设置 → Webhook · 自动消息。创建和删除 Webhook 需要 MANAGE_CHANNELS 权限。请保存返回的路径和令牌：密钥只显示一次，数据库中只保存它的哈希值。

账户令牌	操作
GET /api/channels/:channelId/webhooks	列出 Webhook。
POST /api/channels/:channelId/webhooks	{name, author_name?, avatar_url?} → 201 {webhook, token, path}。
DELETE /api/channels/:channelId/webhooks/:id	删除 Webhook。

地址和标识属于该频道所在主机的 API。Webhook 不支持私聊、群组和公开空间。

发送

POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json

{ "embeds": [{
  "title": "构建完成",
  "description": "该版本已可审阅。",
  "color": 5793266,
  "fields": [{ "name": "状态", "value": "就绪", "inline": true }]
}] }

也支持 {"content":"文本"}，最多 2000 个字符。最多 10 个嵌入内容，合计 6000 个字符。当文本与嵌入内容同时出现时，文本会占用一个嵌入位置。成功的 201 响应包含消息 id 和 channel_id。频道由配置决定，而不是请求体。

限制与安全

每个 Webhook 每 2 秒接受一次请求。收到 429 时，请按 Retry-After: 2 等待。
作者和头像在创建 Webhook 时固定，而不是由任意发送方决定。消息会被标记为 Webhook。
发送时会检查创建者的权限。权限丢失可能导致 403。
结果不明的请求不要重复发送，除非先进行核对：目前没有实现幂等。
请把密钥放在 Authorization 中，而不是 URL 里。密钥泄露时请删除并重新创建 Webhook。
避免在通知和外部图片链接中放入个人数据。