#Webhooks

A webhook posts messages into one channel through a secret URL. It needs no bot code, no gateway loop, and no Authorization header — if you can make an HTTP request, you can post to Disband.

Webhooks are separate from bots. Use a webhook for one-way notifications from CI, monitoring, game servers, forms, or anything else that can call a URL. Use a bot when you need to read events or act on messages.

#Create a webhook

You need the Manage Webhooks permission in the space.

1. Open Space Settings → Integrations → Webhooks.
2. Choose a channel and select New webhook.
3. Give it a name and, if you like, an avatar.
4. Copy the webhook URL.

The URL looks like this:

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

The same endpoint is also served at https://disband.dev/api/webhooks/<space key>/<token>.

From that screen you can rename the webhook, reset its token, or delete it. Resetting the token immediately invalidates the old URL. Deleting the webhook stops it posting, but leaves messages it has already sent in the channel.

#Execute a webhook

Send a POST to the webhook URL with a JSON body.

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"
  }'

A successful request returns 204 No Content. Add ?wait=true to receive the created message object instead:

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

#Body fields

username cannot contain disband or clyde, in any casing. That prevents a webhook impersonating platform staff.

File attachments are not supported yet. A multipart request can be parsed, but files are not stored; use a bot if you need to upload files.

#Mention control

By default a webhook parses both user mentions and @everyone / @here, the same as Discord.

To ping nobody:

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

To allow user mentions but not everyone:

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

The database still stores @everyone when it is suppressed, but no notification is sent. When the field is missing entirely, everything is parsed.

#Message objects

With ?wait=true, the response is a Discord-shaped message. Disband uses its numeric message id in 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": "…"
}

#Manage messages

A webhook can fetch, edit, and delete messages it posted. Use the numeric message id from the execute response.

Edit example:

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

Only messages authored by that webhook can be changed. A different webhook receives 404 Unknown Message.

#Manage the webhook itself

Deleting through the URL is permanent and equivalent to deleting it in the Integrations screen.

#Rate limits

Each webhook is limited to 5 requests per 2 seconds. The limit is keyed on the token, so one noisy webhook cannot slow another one down.

A limited request returns 429:

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

The response also carries Retry-After (whole seconds) and the usual X-RateLimit-* headers. Wait for the delay, then retry.

#Errors

Errors use Discord's shape:

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

A 404 Unknown Webhook deliberately does not say whether the space key or the token was wrong.

#Security

• Anyone with the URL can post. Do not commit it to a public repository or put it in client-side code.
• Store the URL in the same secret store you use for API keys.
• Reset the token immediately if it leaks. The old URL stops working at once.
• A webhook only writes to its configured channel. It cannot read messages, list members, or change space settings.

#Related

• Embeds — the embed object and its limits.
• Bots — two-way integrations and event delivery.
• Bot API reference — the bot HTTP API, including embed support.