What a Discord webhook is
A Discord webhook is a URL that posts messages into one channel of a server. Anything that can send an HTTP request can use it: a deploy script, a monitoring check, a cron job, a home automation. No bot account, no login and no library are needed.
This is an incoming webhook: you send to Discord. That is the opposite direction to most webhooks, where a provider such as Stripe sends to you. If the difference is new to you, start with what a webhook is.
How to create a Discord webhook URL
You need the Manage Webhooks permission on the server.
- Open Server Settings → Integrations → Webhooks (or a channel's Edit Channel → Integrations).
- Choose New Webhook, give it a name and an avatar, and pick the channel it posts to.
- Choose Copy Webhook URL.
The URL looks like this:
https://discord.com/api/webhooks/123456789012345678/AbCdEf…token…The number is the webhook's id and the last part is its token. Anyone who has the whole URL can post to your channel, so treat it like a password: keep it out of client-side code, screenshots and public repositories. If it leaks, delete the webhook and create a new one. More on that in what a webhook URL is.
Send your first message
Discord expects a JSON body with at least one of content or embeds:
curl -H "Content-Type: application/json" \
-d '{"content": "Deploy finished ✅"}' \
"https://discord.com/api/webhooks/<id>/<token>"A successful post returns 204 No Content. Add ?wait=true to the URL to get 200 with the created message instead, which you need if you want to edit or delete it later.
The same from Node.js:
await fetch(process.env.DISCORD_WEBHOOK_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
username: "Deploy bot",
content: "Build #42 is live",
allowed_mentions: { parse: [] }, // never ping @everyone by accident
}),
});The fields you will use
| Field | What it does |
|---|---|
content | The message text, up to 2,000 characters. Supports Discord markdown. |
username | Overrides the webhook's name for this message. |
avatar_url | Overrides the avatar for this message. |
embeds | Up to 10 rich embeds: title, description, color, fields, footer, image. |
allowed_mentions | Which mentions may ping. {"parse": []} disables all of them. |
thread_id (query) | Posts into an existing thread of the channel. |
thread_name | Creates a new post when the webhook belongs to a forum channel. |
An embed for an alert:
{
"embeds": [{
"title": "Payment failed",
"description": "Invoice in_1Q… could not be charged.",
"color": 15277621,
"fields": [
{ "name": "Customer", "value": "cus_123", "inline": true },
{ "name": "Amount", "value": "€49.00", "inline": true }
]
}]
}Embed text has its own limits: a title of up to 256 characters, a description of up to 4,096, and 6,000 characters across all embeds of one message.
Rate limits and errors
Discord rate limits webhooks per webhook and per channel. When you go over, it answers 429 Too Many Requests with a retry_after value (in seconds) in the body and a Retry-After header. Wait that long and send again; don't retry in a tight loop. The X-RateLimit-* response headers tell you how much room is left, so a busy sender can slow down before it hits the limit.
The common failures:
- 400 "Cannot send an empty message": the body had neither
contentnorembeds, or it wasn't JSON. Check theContent-Typeheader. - 400 with a field error: a value is over its limit, such as
contentabove 2,000 characters. - 401 or 404 "Unknown Webhook": the webhook was deleted or the token is wrong.
Discord webhook senders and Discohook
Web tools such as Discohook let you compose a message with embeds and buttons visually, preview it, and send it to your webhook URL. They are handy for announcements and rules channels. Remember that pasting the URL into a third-party tool gives that tool your webhook's token.
For scripts, a plain HTTP request is all you need; there is no Discord SDK to install.
Connect GitHub and other services to Discord
Discord only understands its own message format, so most services can't post to a Discord webhook directly: a Stripe or Shopify event isn't a Discord message, and Discord rejects it with a 400.
There are two exceptions built into Discord:
- Add
/githubto the end of the webhook URL and use it as a GitHub webhook (content typeapplication/json). Discord turns pushes, pull requests and issues into messages. - Add
/slackto accept Slack-formatted payloads, so tools that can post to Slack can post to Discord too. See Slack webhooks.
For anything else, put a small step in between that reshapes the event: a serverless function, or a workflow tool like n8n or Zapier.
Make GitHub to Discord reliable with HookStead
HookStead forwards each event's body and the sender's headers unchanged, so it pairs well with Discord's /github endpoint:
- Create a HookStead source with the GitHub signature option and use its URL in GitHub's webhook settings. HookStead verifies GitHub's signature and stores every event.
- Add your Discord URL with
/githubon the end as a destination and connect it. - If Discord answers 429 or is unavailable, HookStead retries with backoff and honors
Retry-After. Every attempt is recorded, and you can replay any event.
HookStead doesn't rewrite payloads, so for other services you still need the reshaping step above. See the GitHub integration.
Webhooks that Discord sends to you
Discord apps can also receive webhooks. In the Discord Developer Portal, an app can register a URL for interactions (slash commands, buttons) and for webhook events such as an app being authorized. Discord signs these with Ed25519 in the X-Signature-Ed25519 and X-Signature-Timestamp headers, and your endpoint must check the signature before acting. The principles are the same as in webhook signature verification.
Frequently asked questions
- How do I get a Discord webhook URL?
- Open Server Settings → Integrations → Webhooks, choose New Webhook, pick a channel and choose Copy Webhook URL. You need the Manage Webhooks permission.
- Is a Discord webhook URL a secret?
- Yes. The last part of the URL is a token, and anyone with the full URL can post to the channel. If it leaks, delete the webhook and create a new one.
- Can a Discord webhook read messages?
- No. A webhook can only post (and edit or delete its own messages). Reading messages needs a bot.
- Why does my Discord webhook return 400?
- Usually the body has neither content nor embeds, isn't valid JSON, or is missing the Content-Type: application/json header. A value over its limit, such as content above 2,000 characters, also returns 400.
- Can Stripe or Shopify post to a Discord webhook directly?
- No. Discord only accepts its own message format (plus GitHub and Slack formats via /github and /slack). Other events need a step in between that turns them into a Discord message.