> ## Documentation Index
> Fetch the complete documentation index at: https://www.towbar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Configure operational notification providers and routes in the Towbar runtime environment.

Operational notification configuration lives only in `TOWBAR_NOTIFICATION_CONFIG_JSON`. The dashboard shows active providers, category routes, and persisted delivery history without exposing credentials or editing controls.

Set `TOWBAR_NOTIFICATIONS_ENABLED=true`, provide a JSON document with `providers` and `routes`, then restart the API. Invalid JSON, duplicate route IDs, missing provider credentials, or invalid destinations fail startup.

```json theme={"system"}
{
  "providers": {
    "slack": { "botToken": "xoxb-..." },
    "smtp": {
      "from": "towbar@example.com",
      "host": "smtp.example.com",
      "port": 587,
      "secure": false,
      "username": "towbar",
      "password": "replace-me"
    },
    "telegram": { "botToken": "123456:...", "chatId": "-100123456" }
  },
  "routes": [
    {
      "id": "deployments-slack",
      "provider": "slack",
      "enabled": true,
      "categories": ["deployments", "previews"],
      "config": { "channelId": "C0123456789" }
    },
    {
      "id": "operations-email",
      "provider": "smtp",
      "enabled": true,
      "categories": ["health", "backups", "restores"],
      "config": { "recipients": ["operations@example.com"] }
    }
  ]
}
```

Slack routes use channel IDs. SMTP routes use recipient arrays. Telegram routes can set a topic `messageThreadId`. Discord routes contain their incoming `webhookUrl`, and generic webhook routes contain their public HTTPS `url`; those two providers need no entry under `providers`.

<div className="towbar-doc-screenshot">
  <div className="towbar-product-light">
    <img src="https://mintcdn.com/avgeek/7IKQY5hBmeQaVMw0/assets/release-v2/notifications-slack-light.jpg?fit=max&auto=format&n=7IKQY5hBmeQaVMw0&q=85&s=36f154ccd053a7910878b8d8a755f054" alt="Configured notification providers and their delivery history appear inside Integrations." width="1280" height="720" loading="lazy" data-path="assets/release-v2/notifications-slack-light.jpg" />
  </div>

  <div className="towbar-product-dark">
    <img src="https://mintcdn.com/avgeek/7IKQY5hBmeQaVMw0/assets/release-v2/notifications-slack-dark.jpg?fit=max&auto=format&n=7IKQY5hBmeQaVMw0&q=85&s=6df69753d6ffab20da2381b0e6bcca4c" alt="Configured notification providers and their delivery history appear inside Integrations." width="1280" height="720" loading="lazy" data-path="assets/release-v2/notifications-slack-dark.jpg" />
  </div>

  <p>
    Only providers enabled by the runtime configuration appear in the
    Integrations sidebar.
  </p>
</div>

## Configure Slack

Add one Slack bot token under `providers.slack`, then add a route for each channel and category combination. Put the channel ID in `config.channelId`. Install the bot in every target channel before restarting Towbar.

## Configure email

Add the SMTP host, port, TLS mode, sender, username, and password under `providers.smtp`. Each SMTP route declares a `config.recipients` array. The same SMTP provider also sends invitation, email-change, password-reset, and other transactional messages to the affected account.

## Configure Discord

Discord uses an incoming webhook per route. Put its full HTTPS URL in `config.webhookUrl`; no shared provider credential is required. Limit the webhook to the intended channel and rotate it in Discord if it is exposed.

## Configure Telegram

Add the bot token and chat ID under `providers.telegram`. A route may set `config.messageThreadId` when the destination is a forum topic. Ensure the bot can post to the configured chat before restarting Towbar.

## Configure webhook push

Generic webhook routes put a public HTTPS `url` directly in their route configuration. Towbar rejects credentials in the URL, private-network destinations, and unsupported ports. Authenticate the request at the receiving service using infrastructure controls appropriate for that endpoint.

Towbar stores provider-neutral events, route IDs, delivery attempts, retry state, provider outcomes, and thread identifiers. Credentials are resolved from the current runtime configuration only when a delivery runs. Removing a route stops future matching deliveries without erasing history. Account and team transactional email uses the configured SMTP provider but selects the affected account as recipient rather than an operational route.

## Delivery history

Open **Manage → Integrations → Notifications → Deliveries** to filter and inspect persisted delivery history. A succeeded delivery means the provider accepted it; it does not prove a person read it.

## Diagnose delivery

Use the delivery row’s status, attempt timestamps, and provider-safe error to distinguish routing, authentication, rate-limit, and temporary transport failures. Correct environment configuration and restart the API for authentication failures. Towbar retries transient failures with bounded backoff; repeated rate limits pause the affected destination rather than blocking application workflows.