Guide · Verified November 17, 2026
Discord target guide
Short answer: A Hooks Discord destination POSTs a message to a channel's incoming webhook URL; that URL carries the token, so it lives in a project secret. Content is plain text with optional embeds, and Discord answers 204 when the message is accepted.
Discord incoming webhooks are the shortest path from an event to a channel: create the webhook in the channel, store its URL as a secret, and write a content template. Embeds add a title, link, and fields when plain text is not enough; the delivery log keeps the reason Discord returns for a 400 or a rate limit.
1. Create an incoming webhook
In the target channel open Settings → Integrations → Webhooks → New Webhook, then copy the webhook URL. It has the shape https://discord.com/api/webhooks/<id>/<token>; the token is the credential, and deleting the webhook in Discord invalidates the URL immediately.
2. Store the URL as a project secret
Settings → Security → Project secrets → add DISCORD_WEBHOOK_URL. The destination config may only reference it as {{secret.DISCORD_WEBHOOK_URL}}; a literal URL is rejected at save time. A URL on a host Discord does not serve webhooks from, or whose path is not /api/webhooks/<id>/<token>, fails with INVALID_DISCORD_WEBHOOK_URL before anything is sent.
Destination config
{
"webhookUrl": "{{secret.DISCORD_WEBHOOK_URL}}",
"content": "New {{event.type}}: {{event.subject.title}}\n{{event.subject.url}}",
"embeds": "{\"title\":\"{{event.subject.title}}\",\"url\":\"{{event.subject.url}}\"}"
}3. Write content and embeds
`content` is the message text and defaults to the event title and URL. `embeds` is optional JSON rendered as one template string: a single embed object or an array of one to ten objects. Invalid JSON, an array outside that range, or non-object entries fail the delivery with INVALID_DISCORD_EMBEDS. If content and embeds both render empty, the delivery fails with EMPTY_DISCORD_MESSAGE. `username` optionally overrides the webhook's display name for that message.
Request Hooks sends
POST https://discord.com/api/webhooks/<id>/<token>
Content-Type: application/json
{"content":"New pull_request.opened: Login fails on Safari\nhttps://github.com/acme/app/pull/7"}4. Read the response and retries
204 is success (200 with ?wait=true also succeeds). A 429 is retryable with DISCORD_RATE_LIMITED, and the message records the server's retry_after seconds. Other failures append Discord's message or error to the HTTP error, so a 400 Invalid Webhook Token is visible in the attempt; 401 and 404 are permanent, and 3xx is blocked as REDIRECT_BLOCKED. Send a test event from the endpoint to check the wiring before a real event arrives; the delivery log shows the status Discord returned.
Frequently asked questions
Where do I get the Discord webhook URL?
In the channel: Settings → Integrations → Webhooks → New Webhook. The URL is bound to one channel, and deleting or regenerating the webhook in Discord invalidates it.
Can I paste the webhook URL directly into the destination?
No. Literal URLs are rejected; store it as a project secret and reference {{secret.DISCORD_WEBHOOK_URL}}, so the token never lands in config JSON, previews, logs, or the console.
Why did my delivery fail with INVALID_DISCORD_EMBEDS?
The rendered embeds string was not valid JSON, was not one to ten objects, or contained a non-object entry. Render only JSON from the template and escape quotes inside strings.
Do embeds replace the content field?
No. Both are optional and can be sent together; at least one must render non-empty, otherwise the delivery fails with EMPTY_DISCORD_MESSAGE.
Reference
- Execute Webhookhttps://discord.com/developers/docs/resources/webhook#execute-webhook
- Rate limitshttps://discord.com/developers/docs/topics/rate-limits
- Payload templateshttps://hooks.events/docs/templates.md
- Secrets & rotationhttps://hooks.events/docs/secrets.md