Notifications

A notification integration connects one organization to Slack or an HTTP endpoint. It defines:

• where messages go;
• which events are sent;
• which stacks are included.

Open Settings → Notifications and select Add Integration.

Configure Slack

Create a Slack app for GantryCD:

1. Create an app in the Slack workspace.
2. Under OAuth & Permissions, add the chat:write bot token scope.
3. Install the app to the workspace.
4. Copy its Bot User OAuth Token. It starts with xoxb-.
5. Invite the app to every channel where it should post.

Then create a Slack integration in GantryCD:

• Default Slack channel: a channel name such as #deployments, or a channel ID.
• Slack bot token: the xoxb- token from the installed app.
• Channel label key: optional routing to a different channel for each stack.

When a stack has a value for the channel label key, GantryCD sends to that value instead of the default channel. The app must be a member of both default and override channels.

The bot token is stored as a secret and is not shown again. Leave the token blank when editing an integration to keep its current value.

Configure a webhook

Use a webhook when another system should receive and process the event. Enter:

• Webhook URL: the HTTP or HTTPS endpoint that receives the request.
• Signing secret: optional secret used to sign the request body.
• Extra headers: optional values such as an Authorization header.

GantryCD sends a POST request with a JSON body. Every request includes:

Content-Type: application/json
User-Agent: GantryCD-Notifications
X-GantryCD-Event: <event type>

The body includes the event type, organization, event time, and related stack when there is one. It also includes an event-specific object such as deployment, stack, scm, or findings.

When a signing secret is set, GantryCD adds this header:

X-GantryCD-Signature-256: sha256=<hex digest>

The digest is HMAC-SHA256 of the raw request body, using the signing secret as the key. Check it before decoding or trusting the payload.

The URL, signing secret, and extra headers are stored as secrets and are not shown again. Leave them blank when editing to keep their current values.

Choose events

An integration sends only the events selected in its Events list. Deployment and preview events are separate, even when they report the same result.

Deployment events

A deployment skipped by a user does not send the auto-skipped event. A command notification includes the command length, but never the command itself.

Preview events

Previews are pull request plans and local plans.

Stack and organization events

Only when the plan changed something

Enable this option to skip notifications when GantryCD measured a plan and confirmed that it had no changes.

The notification is still sent when no plan is available or its result could not be measured. This avoids hiding a real failure or change because analysis was incomplete.

Dependency diagnostics schedule

Selecting Dependency diagnostics changed also shows its report schedule. The format is minute hour * * day-of-week, in UTC:

0 9 * * 1

This example runs on Mondays at 09:00 UTC. A report is sent only when the organization has findings. A clean organization stays quiet.

Filter stacks

Leave Stack label selector empty to receive the selected events for every stack, plus organization-wide events.

Add labels when the integration should cover only part of the organization. Every selector row must match the stack exactly. Extra labels on the stack do not matter.

The selector also applies to stack creation, deletion, rename, and sync events, not only to deployments and previews.

Repository sync failures and dependency diagnostics have no stack. They are sent only through integrations with an empty stack label selector.

For Slack, the selector and channel label key do different jobs:

• The stack label selector decides whether to send the notification.
• The channel label key decides which Slack channel receives it.

Example: route production stacks

Configure one Slack integration like this:

Default Slack channel: #infrastructure
Channel label key:     slack-channel

Stack label selector:
  environment = production

The same integration then handles these stacks as follows:

payments-staging has a channel label, but it does not pass the stack label selector. GantryCD checks the selector first and reads the channel label only for a matching stack.