← Back to documentation

Slack Incoming Webhooks

Create a Slack webhook, save it as a relay target, and test delivery.

3 min read

Use this guide to send endpoint traffic to Slack.

Purpose#

Use this guide to:

  • Create a Slack incoming webhook.
  • Save Slack as a relay target.
  • Attach the target to an endpoint destination.
  • Test delivery.

Before you start#

  • Make sure that you have permission in the Slack workspace to create an incoming webhook.
  • Select the Slack channel that receives the messages.
  • Make sure that you can access Relay targets and Endpoints.

Procedure#

1. Create webhook URL in Slack#

  1. In the Slack app settings, enable Incoming Webhooks.
  2. Create a webhook for the channel.
  3. Copy the URL. Use https://hooks.slack.com/services/... for Slack. GovSlack uses https://hooks.slack-gov.com/services/....

2. Add Slack relay target#

  1. Open Relay targets.
  2. Select Add target.
  3. Select Slack webhook.
  4. Paste the Slack URL into Slack webhook URL and save.

The URL must use the Slack incoming webhook format on hooks.slack.com or hooks.slack-gov.com.

3. Attach Slack target to endpoint#

  1. Open the endpoint create page or the endpoint edit page.
  2. In Outputs, select the Slack target.
  3. If the generated Slack text or the template body sections need Markdown, keep Enable Markdown formatting selected. It is on by default.
  4. Save the endpoint.

4. Send test delivery#

  1. On Relay targets, select Send test for the Slack target.
  2. Make sure that the message appears in the Slack channel.
  3. To see the test result, look for Test accepted (TEST_ACCEPTED) in Activity.

Mentions and escaping#

  • PayloadRelay escapes &, <, and > in the Slack text that it creates from the payload. So a payload value cannot mention @channel, @here, or a user.
  • In a message template with Enable Markdown formatting on, PayloadRelay also escapes these characters in each value that a placeholder inserts. A mention such as <!channel> works only in the literal text that you write in the template.
  • With Enable Markdown formatting off, the template sections are plain text. PayloadRelay escapes the complete fallback text.
  • The title of a template goes into a plain-text header block. Slack does not apply Markdown to the title.
  • PayloadRelay does not change the text of an incoming payload that already has text, blocks, or attachments. That payload controls its own formatting and its own mentions. If it has no mrkdwn field, PayloadRelay adds one from Enable Markdown formatting.

Expected result#

  • The Slack target is listed, and you can select it as an endpoint destination.
  • The test traffic and the live endpoint traffic go to the selected channel.
  • Without a custom message template, PayloadRelay sends the incoming payload as Slack text. With a custom message template, PayloadRelay sends Slack attachment blocks with a top-level text fallback.

Common issues and fixes#

  • URL rejected: make sure that the URL uses hooks.slack.com/services/... or hooks.slack-gov.com/services/....
  • No message in Slack: make sure that the target is attached to the endpoint, and that the webhook is active.
  • Formatting issues: change Enable Markdown formatting for a generated message. Slack-native blocks or attachments in the incoming payload control their own formatting.
← Back to documentation