Discord Webhook Configuration

This guide explains how to set up separate Discord webhooks for commits vs. deployments.

Why Separate Webhooks?

• Commits channel (#commits): Shows all pushes to main/dev branches
• Deployments channel (#deployments): Shows deployment status (success/failure) to staging and production

This separation reduces noise and makes it easier to track what's deployed vs. what's committed.

Setup Instructions

1. Create Discord Channels

In your Discord server:

1. Create two new channels:

   • #commits (Private to team)
   • #deployments (Private to team)

2. Set channel permissions (optional but recommended):

   • Make channels read-only for regular members
   • Only webhook bot can post

2. Create Webhooks

For each channel:

1. Settings → Integrations → Webhooks
2. Click New Webhook
3. Name it (e.g., "Lantern GitHub Bot")
4. Select the channel
5. Click Copy Webhook URL

Result:

#commits channel → DISCORD_WEBHOOK_COMMITS
#deployments channel → DISCORD_WEBHOOK_DEV_DEPLOY, DISCORD_WEBHOOK_PROD_DEPLOY

3. Add Secrets to GitHub

In GitHub repository:

1. Go to Settings → Secrets and variables → Actions
2. Click New repository secret

Add these secrets:

DISCORD_WEBHOOK_COMMITS
├─ URL from #commits webhook

DISCORD_WEBHOOK_DEV_DEPLOY
├─ URL from #deployments webhook (used for dev.ourlantern.app)

DISCORD_WEBHOOK_PROD_DEPLOY
├─ URL from #deployments webhook (used for ourlantern.app)

Note: DISCORD_WEBHOOK_DEV_DEPLOY and DISCORD_WEBHOOK_PROD_DEPLOY can point to the same Discord channel if you prefer, or different channels for separation.

Webhook URLs Format

Each webhook URL looks like:

https://discordapp.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN

⚠️ Keep these secret! Never commit to git or share publicly.

Deprecation

The old DISCORD_WEBHOOK_URL secret is deprecated and should be removed after migration:

1. Delete from GitHub Secrets
2. Verify all workflows use the new secrets
3. Remove any references from documentation

Testing Webhooks

To test a webhook manually:

curl -X POST https://discordapp.com/api/webhooks/YOUR_ID/YOUR_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "Test Bot",
    "content": "Test message from GitHub Actions"
  }'

Expected response: 204 No Content (success)

Troubleshooting

Webhook returns 404

• Webhook URL is incorrect or expired
• Channel was deleted
• Fix: Create a new webhook and update the secret

Webhook returns 401

• Webhook token is invalid or revoked
• Fix: Recreate the webhook

Messages not appearing

• Check webhook is in correct channel
• Verify bot has permission to post in channel
• Check Discord server notifications aren't muted

Rate limiting (429)

• Too many requests to Discord API
• GitHub Actions is sending too many notifications
• Fix: Batch multiple commits in one message (already implemented)

See Also

• CICD_GUIDE.md - Full CI/CD documentation
• deploy-dev.yml - Development deployment workflow
• deploy-prod.yml - Production deployment workflow
• discord-notify.yml - Commit notification workflow