Configure a Slack Integration

Use PayloadRelay to send messages to Slack, and you do not store a Slack API token in each sending service. Configure one Slack target. A system that can send an HTTP request can then post to the Slack channel.

Purpose#

Use this guide to:

• Create a Slack Incoming Webhook and add it as a PayloadRelay target.
• Send structured messages from a script and a service.
• Use the Slack message formatting in a relayed message.
• Send a monitoring alert to Slack.

Before you start#

• Make sure that you can create an Incoming Webhook in the Slack workspace, or get administrator approval.
• Create a PayloadRelay endpoint.
• Configure the endpoint to accept POST with the JSON payload format.

Procedure#

1. Create a Slack Incoming Webhook#

1. Open api.slack.com/apps and create a new app, or use an existing app.
2. In Incoming Webhooks, enable the feature.
3. Select Add New Webhook to Workspace.
4. Select the channel where the messages appear.
5. Copy the webhook URL, for example, https://hooks.slack.com/services/T.../B.../xxxx. GovSlack uses https://hooks.slack-gov.com/services/....

2. Add the Slack target in PayloadRelay#

1. Open Relay targets and select Add target.
2. Select Slack webhook.
3. Paste the Slack Incoming Webhook URL.
4. Give the target a descriptive name, for example, #ops-alerts Slack.
5. Save.

3. Attach the target to an endpoint#

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

PayloadRelay sends a payload that goes to this endpoint to the Slack channel. By default, PayloadRelay puts the incoming payload in the Slack text field. If the payload already contains a Slack text, blocks, or attachments field, PayloadRelay keeps that structure. For a selected notification, enable a custom message template on the Slack destination.

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 sends the payload as Slack text, and the fields thus appear in the Slack channel. For a short title and body instead of the complete payload, use a custom message template.

5. Slack markdown formatting#

Slack supports a subset of Markdown that is called mrkdwn. The Slack text that PayloadRelay creates and the message templates use the Slack Markdown control on the endpoint destination. You can put these formats in the 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 a server monitoring alert to Slack from a cron job or a 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
    }')"

To send a regular health update to Slack, schedule this script with cron:

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

7. Application error notification#

Send an application error to Slack from the 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#

• A message appears in the configured Slack channel.
• The payload fields are visible and formatted in the Slack message.
• A request appears in PayloadRelay Request activity as Completed (ACCEPTED).

Common issues#

• No message in Slack: make sure that the Slack Incoming Webhook URL is valid. Make sure that the app is installed in the Slack workspace.
• The Slack webhook returns invalid_payload: make sure that the payload is valid JSON and in the size limit.
• The formatting is wrong: use the Slack mrkdwn syntax, not the standard Markdown. When you send Slack blocks, the text.type value of each block controls the formatting.
• The channel changed: if the channel name changes, or if Slack makes a new webhook, update the Incoming Webhook URL.

Related guides#

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