When to use a webhook
Use a webhook for build notifications, external service events or updates. It posts to a preselected text channel. To read messages, handle commands and buttons or react to events, use a bot.
Creating a webhook
Open text channel settings → Webhooks · automated messages. Creating and deleting webhooks requires MANAGE_CHANNELS. Save the returned path and token: the secret is shown once and its hash is stored in the database.
| Account token | Operation |
|---|---|
| GET /api/channels/:channelId/webhooks | List webhooks. |
| POST /api/channels/:channelId/webhooks | {name, author_name?, avatar_url?} → 201 {webhook, token, path}. |
| DELETE /api/channels/:channelId/webhooks/:id | Delete a webhook. |
The address and identifier belong to the channel host’s API. Webhooks do not support direct messages, groups or public spaces.
Sending
POST /api/webhooks/:id/execute
Authorization: Bearer <WEBHOOK_TOKEN>
Content-Type: application/json
{ "embeds": [{
"title": "Build ready",
"description": "The version is ready for review.",
"color": 5793266,
"fields": [{ "name": "Status", "value": "Ready", "inline": true }]
}] }{"content":"Text"} is also supported, up to 2000 characters. Up to 10 embeds and 6000 characters in total. When content accompanies embeds, the text uses one embed slot. A successful 201 response contains the message id and channel_id. The channel is set in configuration, not the request body.
Limits and security
- One accepted request per webhook every 2 seconds. On 429, use Retry-After: 2.
- The author and avatar are set when the webhook is created, not by an arbitrary sender. Messages are labeled as webhooks.
- The creator’s permissions are checked on send. Losing permissions may produce 403.
- Do not repeat a request with an unknown result without checking: idempotency is not implemented.
- Send the secret in Authorization, not the URL. Delete and recreate a webhook if its secret leaks.
- Avoid personal data in notifications and external image URLs.