Discord Webhooks: Complete Guide

Create, send, and secure webhooks with embeds, attachments, and rate-limit aware delivery

← Back to Blog

What Are Webhooks?

Discord webhooks are lightweight endpoints tied to a channel that let you send messages without a bot user online. They're perfect for CI notifications, alerts, and cross-app integrations.

Create a Webhook

  1. Open channel settings → Integrations → Webhooks
  2. Click "New Webhook" → Name it and choose a channel
  3. Copy the webhook URL (keep it secret)

Send a Basic Message

curl -H "Content-Type: application/json" \
  -d '{"content":"Hello from a webhook!"}' \
  https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN

Embeds and Username/Avatar Override

{
  "username": "Build Bot",
  "avatar_url": "https://example.com/build.png",
  "embeds": [
    {
      "title": "Deployment Succeeded",
      "description": "Version 1.2.3 is live",
      "color": 3066993,
      "fields": [
        { "name": "Service", "value": "api", "inline": true },
        { "name": "Region", "value": "eu-west-1", "inline": true }
      ]
    }
  ]
}

Security Best Practices

  • Treat webhook URLs like secrets; rotate when exposed
  • Send via server-side code, not public client-side JS
  • Use allowlists and signature checks in your relay if proxying

Rate Limits

Webhook execution has channel-level limits. Respect HTTP 429 by honoring Retry-After headers and implement simple backoff. Batch messages where possible.

Use Cases

  • CI/CD and deployment notifications
  • Error alerts and uptime monitoring
  • Cross-service event relays (GitHub, Stripe, etc.)

Rate Limits (Per Webhook)

Discord applies per‑webhook buckets. Community docs and observed headers indicate around 5 requests per 2 seconds per webhook. Always respect HTTP 429 and the response headers:

  • X-RateLimit-Limit, X-RateLimit-Remaining
  • X-RateLimit-Reset, X-RateLimit-Reset-After
  • Retry-After on 429s

Implement a small queue and backoff using Retry-After. If you need higher throughput, use multiple webhooks in different channels, or move to a bot user with appropriate rate‑limit handling.

Operational Hardening

  • Rotate secrets periodically; revoke on exposure.
  • Don’t expose webhook URLs in client code or public repos.
  • Use proxies to centralize retry/queue logic and apply signature verification if integrating third parties.