Setting Up a Discord Integration

Use PayloadRelay to send messages to Discord channels from any service that can make HTTP requests. Configure a Discord webhook target once and route payloads from endpoints, scripts, and CI/CD pipelines.

Purpose

This guide helps you:

• Create a Discord webhook and add it as a PayloadRelay target.
• Send structured messages to Discord channels.
• Use Discord formatting and embeds.
• Build a deployment notification pipeline.

Prerequisites and permissions

• A Discord server where you have Manage Webhooks permission.
• A PayloadRelay account with an active endpoint.
• The endpoint must accept POST with JSON payload format.

Step-by-step workflow

1. Create a Discord webhook

1. In Discord, open the channel where you want messages to appear.
2. Select Edit Channel (gear icon) → Integrations → Webhooks.
3. Select New Webhook.
4. Set the webhook name and avatar (these appear as the message sender).
5. Copy the webhook URL (e.g. https://discord.com/api/webhooks/1234/abcdef).

2. Add the Discord target in PayloadRelay

1. Open Relay targets and select Add target.
2. Choose Discord webhook.
3. Paste the Discord webhook URL.
4. Give the target a descriptive name (e.g. #deployments Discord).
5. Save.

3. Attach the target to an endpoint

1. Open the endpoint in Endpoints.
2. In Target destinations, add the Discord target.
3. Save.

Payloads sent to this endpoint will now be forwarded to your Discord channel.

4. Send a basic message

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "event": "deploy",
    "version": "3.1.0",
    "environment": "production",
    "status": "success"
  }'

PayloadRelay delivers the payload fields as a formatted message in your Discord channel.

5. Discord markdown formatting

Discord supports a rich subset of Markdown in message content:

Example with formatting:

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "**Deployment Complete** 🚀",
    "details": "Version `3.1.0` deployed to *production*",
    "notes": "> All health checks passed\n> Zero-downtime migration applied"
  }'

6. TTS (Text-to-Speech) option

Discord webhooks support text-to-speech. When enabled, Discord reads the message aloud to users in the channel. PayloadRelay passes through a tts field if included in your payload:

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Critical alert: database failover triggered",
    "tts": true
  }'

TTS is useful for urgent alerts, but use sparingly to avoid disrupting channel members.

7. Deployment notification example

A complete deployment notification pipeline from a CI/CD script:

#!/bin/bash
set -euo pipefail

ENDPOINT="https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID"
VERSION="${1:?Usage: deploy-notify.sh <version>}"
ENVIRONMENT="${2:-production}"
DEPLOYER="${3:-$(whoami)}"

notify() {
  local status="$1"
  local emoji="$2"
  local color="$3"

  curl -s -X POST "$ENDPOINT" \
    -H "Content-Type: application/json" \
    -d "$(jq -n \
      --arg subject "$emoji Deployment $status: v$VERSION" \
      --arg version "$VERSION" \
      --arg env "$ENVIRONMENT" \
      --arg deployer "$DEPLOYER" \
      --arg status "$status" \
      --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      '{
        subject: $subject,
        version: $version,
        environment: $env,
        deployed_by: $deployer,
        status: $status,
        timestamp: $time
      }')"
}

# Before deployment
notify "started" "🔄" "3447003"

# Run your deployment
if ./deploy.sh "$VERSION" "$ENVIRONMENT"; then
  notify "succeeded" "✅" "3066993"
else
  notify "failed" "❌" "15158332"
  exit 1
fi

Usage:

./deploy-notify.sh 3.1.0 production alice

8. Scheduled status report

Send a daily status report to Discord from a cron job:

#!/bin/bash
ENDPOINT="https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID"

UPTIME=$(uptime -p 2>/dev/null || uptime | awk '{print $3,$4}')
LOAD=$(uptime | awk -F'load average:' '{print $2}' | xargs)
DISK=$(df -h / | awk 'NR==2 {printf "%s used of %s (%s)", $3, $2, $5}')

curl -s -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg subject "📊 Daily Status Report — $(hostname)" \
    --arg uptime "$UPTIME" \
    --arg load "$LOAD" \
    --arg disk "$DISK" \
    --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    '{
      subject: $subject,
      uptime: $uptime,
      load_average: $load,
      disk: $disk,
      timestamp: $time
    }')"

Expected result and verification checks

• Messages appear in the configured Discord channel.
• Payload fields are formatted and readable in the Discord message.
• Requests appear in PayloadRelay Request activity with outcome ACCEPTED.
• Markdown formatting renders correctly in Discord.

Common issues and fixes

• No message in Discord: verify the Discord webhook URL is still active and hasn't been deleted.
• Webhook URL rejected: Discord webhook URLs must start with https://discord.com/api/webhooks/ or https://discordapp.com/api/webhooks/.
• Formatting not rendering: use Discord Markdown syntax (double asterisks for bold, etc.), not Slack mrkdwn.
• Rate limits: Discord has its own rate limits on webhooks. If messages are dropped, check PayloadRelay Request activity for delivery failures and enable retries on the endpoint.

Related guides

• Relay Targets
• Setting Up a Slack Integration
• Multicasting a Webhook
• Getting Started