#Webhook

Webhook通过一个秘密的URL将消息发布到一个频道。它不需要机器人代码、网关循环和Authorization头——如果你可以发送HTTP请求，你就可以发布到Disband。

Webhooks与机器人是分开的。使用webhook从CI、监控、游戏服务器、表单或任何其他可以调用URL的东西发送单向通知。当你需要读取事件或处理消息时，请使用机器人。

#创建一个webhook

你需要在空间中拥有管理Webhooks权限。

1. 打开空间设置→集成→Webhooks。
2. 选择一个频道，然后选择新webhook。
3. 给它起个名字，如果你愿意，还可以给它一个头像。
4. 复制网络钩子URL。

URL看起来像这样：

https://disband.dev/webhook/12345678/01234567890123456789012345

相同的端点也在https://disband.dev/api/webhooks/<space key>/<token>上提供服务。

从该屏幕中，你可以重命名网络钩子、重置其令牌或删除它。重置令牌会立即使旧的URL失效。删除网络钩子会停止它发布消息，但会保留它已经在频道中发送的消息。

#执行一个webhook

将POST发送到webhook URL，并附上JSON的正文。

curl -X POST 'https://disband.dev/webhook/12345678/01234567890123456789012345' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Deploy finished — **v2.4.1** is live.",
    "username": "Deploy bot",
    "avatar_url": "https://example.com/deploy.png"
  }'

成功请求返回204 No Content。添加?wait=true以接收创建的消息对象：

curl -X POST 'https://disband.dev/webhook/12345678/01234567890123456789012345?wait=true' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Hello from the other side." }'

#身体字段

username在任何封装中都不能包含disband或clyde。这防止了网络钩子冒充平台员工。

目前不支持文件附件。可以解析多部分请求，但文件不会存储；如果你需要上传文件，请使用机器人。

#提及控制

默认情况下，webhook会解析用户提及和@everyone / @here，与Discord相同。

向没有人发送ping：

{ "content": "Build 184 finished.", "allowed_mentions": { "parse": [] } }

允许用户提及，但不允许所有人：

{
  "content": "Thanks @polar.",
  "allowed_mentions": { "parse": ["users"] }
}

当@everyone被禁用时，数据库仍然会存储该值，但不会发送通知。当字段完全缺失时，所有内容都会被解析。

#消息对象

使用?wait=true，响应是一个Discord形状的消息。Disband使用id中的数字消息ID。

{
  "id": "4821",
  "type": 0,
  "content": "Deploy finished.",
  "channel_id": "…",
  "guild_id": "…",
  "author": {
    "id": "…",
    "username": "Deploy bot",
    "avatar": "https://example.com/deploy.png",
    "discriminator": "0000",
    "bot": true
  },
  "attachments": [],
  "embeds": [],
  "mentions": [],
  "mention_roles": [],
  "mention_everyone": false,
  "pinned": false,
  "tts": false,
  "timestamp": "2026-10-19T20:15:00.000Z",
  "edited_timestamp": null,
  "flags": 0,
  "components": [],
  "webhook_id": "…"
}

#管理消息

Webhook可以获取、编辑和删除它发布的消息。使用执行响应中的数字消息ID。

编辑示例：

curl -X PATCH 'https://disband.dev/webhook/12345678/01234567890123456789012345/messages/4821' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Deploy finished — rolled back." }'

只有由该webhook撰写的消息才能更改。不同的webhook接收404 Unknown Message。

#管理webhook本身

通过URL删除是永久性的，相当于在集成屏幕中删除它。

#速率限制

每个webhook每2秒限5个请求。限制取决于令牌，因此一个嘈杂的webhook不能减慢另一个webhook的速度。

有限请求返回429：

{
  "message": "You are being rate limited.",
  "retry_after": 1.34,
  "global": false
}

响应还带有Retry-After（整秒）和通常的X-RateLimit-*头。等待延迟，然后重试。

#错误

错误使用Discord的形状：

{ "message": "Unknown Webhook", "code": 10015 }

404 Unknown Webhook故意没有说是空格键还是令牌出了问题。

#安全

• 任何持有URL的人都可以发布。请勿将其提交到公共存储库或放置 它在客户端代码中。
• 将URL存储在与API密钥相同的秘密存储中。
• 如果令牌泄露，请立即重置令牌。旧的URL将立即停止工作。
• Webhook只向其配置的频道写入数据。它无法读取消息， 列表成员，或更改空间设置。

#有亲属关系的

• 嵌入 — 嵌入对象及其限制。
• 机器人 — 双向集成和事件交付。
• API 参考 — 机器人HTTP API，包括 嵌入支持。