Webhooks | Klang Docs

What you can do with one

A webhook is a one-way door into a channel: whatever has its URL can post there. Some of the things people use them for:

GitHub. Pushes, pull requests, issues and releases in your project’s channel. Klang turns GitHub’s events into embeds; see GitHub.
Game servers. Someone joined, the server restarted, a match ended, a backup failed.
Alerts. Uptime monitors, CI pipelines, error trackers and home automation that already know how to notify Discord.
RSS and no-code tools. Zapier, IFTTT and Make can post new feed items, form answers or calendar events with their Discord webhook action.
Your own scripts. A cron job or a deploy script that says when it’s done, with a single HTTP request and no library.

Webhooks only post. They can’t read the channel, answer commands or join voice: that’s what bots will be for.

Create a webhook

Open Server settings › Integrations › Webhooks. A channel’s own webhooks are also under Edit channel › Integrations.
Create one and give it a name, an avatar and the channel it posts to.
Copy its URL and paste it in the service that will post.

You need the Manage webhooks permission in that channel. Owners and administrators have it; anyone else can get it from a role or from the channel’s permissions. With it you can also rename a webhook, change its avatar, move it to another channel, regenerate its token and delete it. Creating, editing and deleting webhooks shows up in the server’s audit log.

A few rules:

Webhooks belong to a text channel in a server. Direct messages, groups and voice channels don’t have them.
Up to 15 webhooks per channel and 50 per server, on every plan.
The name is 1 to 80 characters. It can’t contain “Klang” or be everyone or here, so a webhook can’t pass itself off as the Klang team.

The webhook URL

URL

https://api.klang.gg/api/webhooks/{webhook.id}/{webhook.token}

webhook.id is the webhook’s ID.
webhook.token is a random secret of 64 characters. It’s the only thing that authorizes posting: there’s no other key and no account behind it.

You can copy the URL again whenever you need it, from the same place you created the webhook. Only people with Manage webhooks in that channel can see it.

Use it where Discord is expected

Klang’s webhooks take the same URL shape, JSON body and responses as Discord’s. Most services that “post to a Discord webhook” work as they are: paste the Klang URL in the field that asks for the Discord webhook URL. Discord webhook libraries work too, as long as they let you pass the whole URL.

Some services only accept discord.com URLs. A few check that the URL starts with https://discord.com/api/webhooks/ and refuse anything else. For those, use their generic “webhook” or “HTTP request” action with a JSON body, or a tool like Zapier or Make in between.

Klang understands content, username, avatar_url, rich embeds, allowed_mentions and the SUPPRESS_EMBEDS flag, and fields it doesn’t know are ignored, as in Discord. Files, buttons, polls and threads aren’t supported yet. The details are in Execute a webhook.

How its messages look

A webhook’s message is a normal message in the channel: it counts for unread and mentions, shows up in search, gets link previews and goes through the server’s AutoMod. It carries the webhook’s name and avatar, or the ones that message sent, and a tag that says it comes from a webhook, so it never looks like a person.

Posting doesn’t depend on the channel’s permissions: the token is all it takes. A webhook posts even where @everyone can’t send messages, and slow mode and the server’s verification level don’t apply to it. Moderators with Manage messages can delete its messages like anyone else’s, and anyone can report them.

Keep the URL secret

Treat the URL like a password. Anyone who has it can post in the channel as the webhook. Keep it out of public repositories, screenshots and chats, and store it where your service keeps its secrets, such as an environment variable.

If it leaks, regenerate the token in Server settings › Integrations › Webhooks. The old URL stops working at once; paste the new one wherever the webhook is used. Or delete the webhook if you don’t need it any more.

What someone with a leaked URL can’t do:

Read anything. The URL only posts: it can’t see the channel’s messages, its members or anything else in the server.
Touch other people’s messages. It can edit or delete only the messages that webhook posted.
Notify everyone. @everyone and @here only notify if the webhook has Can mention @everyone turned on. It’s off by default, and only people who can mention everyone in that channel can turn it on.
Guess other URLs. Requests with a wrong token are limited by IP address, and the token is never written to Klang’s logs.