Setting Up a Slack Integration

Use PayloadRelay to relay messages to Slack channels without managing Slack API tokens in each sending service. Configure a Slack target once and any system that can send HTTP requests can post to your Slack channel.

Purpose

This guide helps you:

• Create a Slack Incoming Webhook and add it as a PayloadRelay target.
• Send structured messages from scripts and services.
• Use Slack markdown formatting in relayed messages.
• Build a monitoring alert pipeline to Slack.

Prerequisites and permissions

• A Slack workspace where you can create Incoming Webhooks (or admin approval to do so).
• A PayloadRelay account with an active endpoint.
• The endpoint must accept POST with JSON payload format.

Step-by-step workflow

1. Create a Slack Incoming Webhook

1. Go to api.slack.com/apps and create a new app (or use an existing one).
2. Under Incoming Webhooks, toggle the feature on.
3. Select Add New Webhook to Workspace.
4. Choose the channel where messages should appear.
5. Copy the webhook URL (e.g. https://hooks.slack.com/services/T.../B.../xxxx; GovSlack URLs use https://hooks.slack-gov.com/services/...).

2. Add the Slack target in PayloadRelay

1. Open Relay targets and select Add target.
2. Choose Slack webhook.
3. Paste the Slack Incoming Webhook URL.
4. Give the target a descriptive name (e.g. #ops-alerts Slack).
5. Save.

3. Attach the target to an endpoint

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

Any payload sent to this endpoint will now be forwarded to your Slack channel. By default, PayloadRelay puts the incoming payload into Slack's text field. If the incoming payload already contains Slack-native text, blocks, or attachments, PayloadRelay preserves that shape. For curated notifications, enable a custom message template on the Slack output.

4. Send a basic message

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "alert": "Deployment complete",
    "version": "2.4.0",
    "environment": "production"
  }'

PayloadRelay delivers the payload as Slack text, so the fields are visible in your Slack channel. Use a custom message template when you want a concise title/body layout instead of the full payload.

5. Slack markdown formatting

Slack supports a subset of markdown called mrkdwn. PayloadRelay's generated Slack text and message templates respect the Slack Markdown toggle on the endpoint output. You can include formatting in your payload values:

Example with formatting:

curl -X POST https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "*Deployment Complete* :rocket:",
    "details": "Version `2.4.0` deployed to _production_ by <@U012345>",
    "link": "<https://example.com/status|View Status>"
  }'

6. Monitoring alert example

Send server monitoring alerts to Slack from a cron job or monitoring script:

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

CPU=$(top -l 1 | grep "CPU usage" | awk '{print $3}' | tr -d '%')
MEM=$(vm_stat | awk '/Pages active/ {print $3}' | tr -d '.')
DISK=$(df -h / | awk 'NR==2 {print $5}')
HOSTNAME=$(hostname)

# Alert if disk usage exceeds 80%
DISK_PCT=${DISK%\%}
if [ "$DISK_PCT" -gt 80 ]; then
  SEVERITY="critical"
  EMOJI=":red_circle:"
else
  SEVERITY="info"
  EMOJI=":large_green_circle:"
fi

curl -s -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg subject "$EMOJI Server Health: $HOSTNAME" \
    --arg severity "$SEVERITY" \
    --arg cpu "$CPU%" \
    --arg disk "$DISK" \
    --arg host "$HOSTNAME" \
    --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    '{
      subject: $subject,
      severity: $severity,
      cpu_usage: $cpu,
      disk_usage: $disk,
      hostname: $host,
      timestamp: $time
    }')"

Schedule this script with cron to get periodic health updates in Slack:

# Run every 15 minutes
*/15 * * * * /path/to/health-check.sh

7. Application error notification

Forward application errors to Slack from your backend:

import requests
import traceback

PAYLOADRELAY_URL = "https://api.payloadrelay.com/relay/YOUR_ENDPOINT_ID"

def notify_error(error, context=None):
    requests.post(PAYLOADRELAY_URL, json={
        "subject": f"Application Error: {type(error).__name__}",
        "error": str(error),
        "traceback": traceback.format_exc(),
        "context": context or {},
        "severity": "error",
    })

# Usage
try:
    process_order(order_id)
except Exception as e:
    notify_error(e, context={"order_id": order_id})
    raise

Expected result and verification checks

• Messages appear in the configured Slack channel.
• Payload fields are visible and formatted in the Slack message.
• Requests appear in PayloadRelay Request activity with outcome ACCEPTED.

Common issues and fixes

• No message in Slack: verify the Slack Incoming Webhook URL is still valid and the app is installed in the workspace.
• Slack webhook returns invalid_payload: confirm the payload is valid JSON and within size limits.
• Formatting not rendering: use Slack's mrkdwn syntax, not standard Markdown. If you send Slack-native blocks, each block's text.type controls whether formatting is enabled.
• Channel changed: update the Incoming Webhook URL if the channel was renamed or the webhook was regenerated.

Related guides

• Relay Targets
• Slack Incoming Webhooks
• Getting Started
• Multicasting a Webhook