Integrations

Slack

Post config changes and alerts to the Slack channels you choose. What each message says, how to create the incoming webhook in Slack, who a message notifies, and what happens when Slack stops accepting messages.

Introduction

A Slack integration posts the changes and alerts you choose to one Slack channel. ConfigDirector writes every message: who changed what, or what an alert found, in one sentence and one more line, with a link to the dashboard. The only text you add is a message prefix, which is how a message notifies people.

You connect a channel by pasting an incoming webhook URL that you create in a Slack app of your own. There is nothing to install from the Slack Marketplace and no review by Slack to wait for, so a channel can get its first message a few minutes after you start.

Integrations belong to the organization, and only owners and admins can see and manage them. They work the same on Free and Pay as you go.

One integration per channel

An integration posts to one channel, with its own choice of changes and alerts, its own message prefix and its own on and off switch. To send different things to different channels, create one integration for each channel. Acme uses three:

IntegrationPostsMinimum priorityMessage prefix
#releasesConfig and targeting rule changes in Production, and no alertsNone
#platformThe application request alertsHigh<!subteam^S0123ABC>, which notifies the @platform-team user group
#incidentsThe alerts that can reach Critical, such as In-code default value served too often, and no changesCritical@here

When the payments-enabled kill switch starts serving its in-code default value to some of its evaluations in Production, an alert is raised at High. #platform gets it and notifies the platform team, while #incidents gets nothing yet. If the share keeps growing, the alert's priority rises to Critical: #incidents gets the whole alert with @here, and #platform gets a short line saying it is now Critical. When the alert resolves, both channels get one line saying so, and nobody is notified.

What a Slack integration posts

Every message appears under the name and icon of the Slack app you create when you connect a channel, ConfigDirector in these examples.

A change

When a member makes a change the integration posts, the channel gets one message within seconds:

ConfigDirectorAPP

Maya Chen updated the targeting rules of checkout-redesign in Production

Default targeting rule value: Disabled → Enabled · Rules changed

Storefront · View change
  • The first line names the member and what they changed. A member without a name is shown by their email, and a member who has left the organization as "A removed member".
  • The second line says what changed, on updates only. A short value is shown before and after, like the default targeting rule value above; a longer value, a list or a set of rules is named as changed. A run that starts or changes its split shows its shares instead, such as control 50%, treatment-a 50%.
  • The last line names the project and links to the change in the dashboard. A change made outside the dashboard also says how it was made, such as through Terraform, through the API, through the MCP server or through the CLI, and names the API token used. A deleted or archived entity has no page left to open, so its message has no link.

A change is posted whether a member makes it in the dashboard or through an API token. Changes ConfigDirector makes on its own, such as a config's lifecycle state moving to settled, post nothing; choose the matching alert, such as Config settled, to hear about those.

An alert

When an alert of a kind the integration posts is raised at its minimum priority or above, the channel gets:

ConfigDirectorAPP

@here

🔴 Critical · payments-enabled served its in-code default value for 52% of evaluations in Production

1,604 evaluations of payments-enabled in Storefront / Production received the in-code default value, 52% of the 3,085 evaluations in the last 24 hours. Reasons: Evaluated before the client was ready (1,604).

View alert
  • The first line is the integration's message prefix, here @here, when it has one.
  • Then comes the priority, as a colored circle and its name: ⚪ Low, 🟡 Medium, 🟠 High or 🔴 Critical. The subject and summary after it are the ones the alert's email uses. Alerts describes every kind.
  • The link opens the alert in the dashboard, with its details and what to do.

The priority never notifies anyone by itself; only the message prefix does.

When an alert's priority rises

An alert can be raised at one priority and rise later, for example when more evaluations are affected. A Slack integration follows it:

  • An alert raised below the integration's minimum priority is posted in full the first time its priority rises to the minimum.
  • An alert the channel already got is followed by a short line each time its priority rises, opened by the message prefix:
ConfigDirectorAPP

@platform-team

🔴 Now Critical, was High · payments-enabled served its in-code default value for 52% of evaluations in Production
View alert

Nothing is posted when an alert's priority falls.

When an alert resolves

When an alert resolves, each channel that got it gets one line, without the message prefix, so good news never notifies anyone:

ConfigDirectorAPP
✅ Resolved · payments-enabled served its in-code default value for 52% of evaluations in Production
View alert

Turn off Post when an alert resolves to leave these lines out. A channel that never got the alert, because the alert stayed below its minimum priority, gets nothing when it resolves.

The test message

Send test message on the integration's page posts this message right away, opened by the integration's message prefix:

ConfigDirectorAPP

@here

ConfigDirector test message from the integration "#incidents". Messages this integration posts will look like this one.

Before it posts, the dialog says who the message prefix will notify.

Connect a channel

Create the incoming webhook in Slack

  1. Open api.slack.com/apps and sign in to your workspace.
  2. Click Create New App.
  3. Select Pick features, then click Continue.
  4. Enter the App Name, select your workspace and create the app. Messages are posted under the app's name, so a name like ConfigDirector tells the channel where they come from.
  5. In the app's settings, select Incoming Webhooks.
  6. Turn on Activate Incoming Webhooks.
  7. Click Add New Webhook to Workspace.
  8. Pick the channel the integration will post to, then select Authorize. To pick a private channel, join it first.
  9. Copy the new URL under Webhook URLs for Your Workspace. It starts with https://hooks.slack.com/services/.

The URL posts to that one channel only. For another channel, click Add New Webhook to Workspace again in the same app, and create another integration with the new URL.

Keep the URL secret: anyone who has it can post to the channel. Slack also revokes any webhook URL it finds published online. Slack's guide, Sending messages using incoming webhooks, covers these steps in more detail.

Check the URL

Before you paste the URL into ConfigDirector, post one line with it from a terminal. The first command waits for you to paste the URL and press Enter, which keeps the URL out of your shell history:

read -rs SLACK_WEBHOOK_URL
curl -X POST -H 'Content-type: application/json' --data '{"text":"ConfigDirector will post here."}' "$SLACK_WEBHOOK_URL"

Slack answers ok, and the line appears in the channel. Any other answer means the integration would fail too:

  • invalid_token or no_service: the URL was copied wrong, or the webhook was removed. Copy it again from Webhook URLs for Your Workspace.
  • channel_is_archived: the channel no longer accepts messages. Add a webhook for another channel.

Create the integration

  1. Open Integrations at the bottom of the dashboard's navigation and pick Slack, or click Add integration when you already have one.
  2. Under Channel, name the integration after the channel, such as #incidents, and paste the URL into Webhook URL. ConfigDirector cannot read the channel from the URL, so the name is how you tell your Slack integrations apart.
  3. Under Message prefix, type the mentions that should be notified, or leave it empty. See Notify people with the message prefix.
  4. Under Changes and Alerts, choose what the channel gets. See Choose what a channel gets.
  5. Under Filters, narrow it down by project, environment and tag, or leave them empty.
  6. Keep Enabled on, then click Create integration.
  7. On the integration's page, click Send test message and confirm. The test message appears in the channel, and under Deliveries on the page.

Choose what a channel gets

A new Slack integration starts with the config and targeting rule changes, and the six application request alerts at High and above, in every project and environment. Change any of it when you create the integration or later from Edit.

Changes

Changes lists every change a Slack integration can post, grouped by what changed:

GroupChanges
ConfigsCreated, Updated, Archived, Restored
Targeting rulesUpdated
Experiment runsStarted, Split changed, Variation shipped, Stopped
SegmentsCreated, Updated, Deleted
MetricsCreated, Updated, Deleted
EnvironmentsCreated, Updated, Deleted
ProjectsCreated, Updated, Deleted

These are the changes webhooks send. Tags, SDK keys, API tokens, members, billing and deleting a config post nothing.

Alerts and the minimum priority

Alert kinds lists every alert kind, grouped as on the alerts page's email preferences, with the priority each kind can have. Minimum priority is the lowest priority this channel gets, one setting for all the kinds you choose: Low and up, Medium and up, High and up or Critical only. An alert of a chosen kind is posted when it is raised at the minimum or above, or later, when its priority rises to the minimum. A chosen kind that can never reach the minimum is marked as never posted.

Post when an alert resolves is on for a new integration; see When an alert resolves.

Filters

The Projects, Environments and Tags filters apply to changes and alerts alike. A change or an alert is posted only when every filter lets it through, and an empty filter lets everything through.

  • A change is checked against its project, its environment and its config's tags. A change that belongs to no environment, such as a change to a config's description, passes any environment filter, and a change that names no config, such as a change to a segment, passes any tag filter.
  • An alert is checked against what it is about. An alert about a config in Production is checked against the config's project, Production and the config's tags. An alert that names no environment or no config passes that filter, and an alert about the whole organization, such as a billing alert or Integration disabled, passes every filter.

The webhooks page lists what each alert kind is checked against.

Notify people with the message prefix

The message prefix is one line, up to 200 characters, that opens every message the integration posts, except the line for a resolved alert. It is the only part of a message that can notify anyone: config keys, names, descriptions and values are posted as plain text, so an @here typed into a config's description notifies no one.

Type in the message prefixNotifies
@hereThe members of the channel who are active in Slack
@channelEvery member of the channel, active or not
@everyoneEvery person in the workspace's general channel, which is every member who is not a guest
<!subteam^S0123ABC>Every member of a user group, here the one with the ID S0123ABC

Anything else, a user group's handle such as @platform-team included, is posted as plain text and notifies no one. Leave the message prefix empty to notify no one at all. A message still shows as new in the channel either way.

Mention a user group

User groups exist on paid Slack plans only. To mention one, type its ID in Slack's own form, <!subteam^ID>, and Slack shows the group's handle in its place, such as @platform-team. To find the ID:

  1. Open Slack in a browser.
  2. From the Home tab, click Directories.
  3. Click User Groups, then click the group.
  4. Copy the last part of the page's address, which starts with S.

Every mention in the table uses the form Slack documents for apps. So far, @here has been seen to notify people from a ConfigDirector message in a real Slack workspace, and @channel and @everyone only from a simpler message. A user group mention has not been tried yet, because that needs a paid workspace, and neither has a mention typed into a name or a value. Click Send test message and see who it notifies before you rely on a mention.

Delivery

A change is normally posted within a few seconds. An alert is posted within seconds of being raised, and alerts are raised by checks that run every 30 minutes or every hour, depending on the kind.

Each integration posts one message at a time, in the order the changes and alerts happened, and at most one a second, the pace Slack accepts for a channel. A message that fails is tried again after about 1 minute, 5 minutes, 30 minutes, 2 hours and 8 hours, and is failed if the last attempt fails too; a message waiting for its next attempt does not hold back the ones after it. When Slack asks ConfigDirector to slow down, the next attempt waits as long as Slack asks.

The integration's page lists its Deliveries from the last 30 days, newest first, with Failures only to show just the failed ones. Each delivery shows what it posted, such as targeting_rules.updated or alert.created, its status and the number of attempts, and expands to the message as it was posted and Slack's answer. Resend posts a delivery's message again right away. If Slack rejects a message as malformed, that delivery fails without another attempt, and the integration stays enabled.

When an integration is disabled

An owner or admin can disable an integration from its page. ConfigDirector also disables a Slack integration on its own:

  • Right away, when Slack refuses a message for good: the channel was archived or deleted, the webhook URL was removed or its Slack app was uninstalled, the workspace no longer exists or is disabled, or a setting of the workspace stops the webhook from posting to the channel.
  • After three days of failures, when messages were attempted on each of the last three days and none of them was posted, for example because Slack kept timing out.

Then it:

  • abandons the messages still waiting to be posted,
  • marks the integration Disabled in the list, and says on its page why, with Slack's reason for a refusal,
  • raises the Integration disabled alert, which is Critical, goes to owners and admins, and is emailed right away unless they turned that off in their email preferences.

While an integration is disabled, nothing is posted, and changes and alerts that happen in the meantime are not posted later. To post again, fix the cause first: after a refusal, click Replace the webhook URL on the integration's page, then Replace, paste a URL for a channel that accepts messages and save. Then click Enable on the integration's page. Enabling it without fixing the cause gets the next message refused again. The alert resolves when the integration is enabled again or deleted.

Replacing the webhook URL

The webhook URL is stored encrypted and never shown again. The integration's page shows when it was saved and by whom. To replace it, for example to post to another channel or after Slack removed the webhook, click Edit, click Replace next to the saved URL, paste the new URL and save. If the new URL posts to another channel, rename the integration to match.

Limits

LimitValue
Slack integrations per organization20, counted apart from the 10 analytics integrations and the 10 webhooks
Name200 characters
Message prefix200 characters
Webhook URL2,048 characters, starting with https://hooks.slack.com/services/
PaceOne message a second for each integration
Delivery history30 days, after which deliveries are deleted and can no longer be resent

Managing Slack integrations as code

Everything on this page is also available through the Admin API, with the kind slack, and through the configdirector_integration resource of the Terraform provider, from version 0.11.0. The API token needs the integrations:manage permission, which only owners and admins can grant, and only to a token with all projects.