musingfox/Discord Webhook

Discord Webhook Notification

Send messages to Discord channels via webhook HTTP POST. Supports plain text and rich Embed format with multi-webhook routing.

Overview

Discord webhooks accept JSON payloads via HTTP POST. This skill handles:

1. Resolve webhook URL from environment variables or settings file
2. Format the message as plain text (content) or rich Embed
3. Send via HTTP POST using curl

Step 1: Resolve Webhook URL

Before resolving, source the project .env file if it exists:

[ -f .env ] && source .env

Then check environment variables:

1a: Named Webhook (when a target name is specified)

Look for environment variable DISCORD_WEBHOOK_{NAME} where {NAME} is the uppercase target name:

# Examples:
# Target "deploy" → DISCORD_WEBHOOK_DEPLOY
# Target "alerts" → DISCORD_WEBHOOK_ALERTS

1b: Default Webhook

Look for environment variable DISCORD_WEBHOOK_URL.

Error Handling

If no webhook URL is found, inform the user:

No Discord webhook URL configured. Add to your .env file:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your/webhook

For named targets, use DISCORD_WEBHOOK_{NAME} (e.g., DISCORD_WEBHOOK_DEPLOY).

Do NOT proceed without a valid webhook URL.

Step 2: Format the Message

Plain Text

For simple string messages, use the content field:

{
  "content": "Deploy v1.2.3 completed successfully"
}

content has a 2000 character limit. Truncate with … if exceeded.

Embed Format

For structured information (deploy reports, error alerts, build status), use the embeds array:

{
  "embeds": [{
    "title": "Deploy Complete",
    "description": "Version **v1.2.3** deployed to production",
    "color": 3066993,
    "fields": [
      { "name": "Environment", "value": "production", "inline": true },
      { "name": "Duration", "value": "2m 34s", "inline": true }
    ],
    "footer": { "text": "Deployed by Claude Code" },
    "timestamp": "2026-04-10T12:00:00.000Z"
  }]
}

Format Selection Guidelines

| Scenario | Format | Reason | |----------|--------|--------| | Simple status update | Plain text | Short, no structure needed | | Error alert with details | Embed | Structured fields, color coding | | Build/deploy report | Embed | Multiple data points | | Quick notification | Plain text | Minimal overhead | | Multi-field data | Embed | Fields layout is clearer |

Common Embed Colors

| Purpose | Color (decimal) | Hex | |---------|----------------|-----| | Success | 3066993 | #2ECC71 | | Error | 15158332 | #E74C3C | | Warning | 15105570 | #E67E22 | | Info | 3447003 | #3498DB | | Default | 9807270 | #959B86 |

Step 3: Send the Message

Use curl to POST the JSON payload:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello from Claude Code"}' \
  "$WEBHOOK_URL"

Response Handling

| HTTP Status | Meaning | Action | |-------------|---------|--------| | 204 | Success (no content) | Message sent successfully | | 400 | Bad request | Check JSON payload format | | 401 | Unauthorized | Webhook URL is invalid or revoked | | 404 | Not found | Webhook has been deleted | | 429 | Rate limited | Wait and retry (respect Retry-After header) |

On success (204), confirm to the caller that the message was sent. On failure, report the HTTP status code and suggest corrective action.

Rate Limiting

Discord webhooks have a rate limit of ~30 requests per minute. If sending multiple messages, add a 2-second delay between requests.

Security Notes

• Never log or echo the full webhook URL — it contains the authentication token
• Store webhook URLs in .env (gitignored)
• Sanitize user-provided content before embedding in JSON to prevent injection
• Use jq -Rs . to safely escape strings for JSON embedding:

  SAFE_MSG=$(echo "$RAW_MSG" | jq -Rs .)
  

Tool Selection

• Use Bash with curl for sending webhook requests (most reliable for JSON payloads)
• Use Bash with jq for JSON construction with dynamic values