> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/july2026/recipes/route-failures-to-slack-or-teams.md).

# Route plan and run failures to Slack or Teams

Once a data product is published, wire Vulcan's notification\_targets so a failed plan or run pages Slack or Teams automatically, instead of waiting for someone to notice it in the logs.

Use notifications once a published product runs unattended. `notification_targets` in `config.yaml` sends Slack or Teams alerts when a `prod` plan or run fails. The failure reaches a channel instead of remaining in a log.

By the end of this recipe, `config.yaml` has a `notification_targets` block routing plan and run failures to Slack or Teams, and you've confirmed delivery end-to-end against a real failure.

## Before you begin

{% hint style="info" %}

* The product is already scaffolded and connected (see [Init and configuration](https://v2.dataos.info/build/july2026/productize/init-and-configuration.md) if not).
* A Slack or Teams channel you have permission to add an integration to (an Incoming Webhook for Slack, a **Workflow** for Teams).
* Access to set environment variables wherever Vulcan runs: shell, CI pipeline, or scheduler. A webhook URL is a secret and needs a home outside `config.yaml`.
* `curl`, to test the webhook independently of Vulcan.
* **A reasonably recent Vulcan build.** `teams_webhook` support is confirmed present in `0.228.1.26`, confirmed absent in `0.228.1.23` and earlier. On an older pin, `type: teams_webhook` fails as an unrecognized target, and the data-quality events are still named `check_start`/`check_end`/`check_failure` instead of today's `dq_start`/`dq_end`/`dq_failure`. Check your pinned image tag before continuing.
  {% endhint %}

## Steps

### 1. Pick Slack or Teams

Vulcan documents exactly four notification target types: `teams_webhook`, `slack_webhook`, `slack_api`, and `smtp` (email). This recipe focuses on Slack and Teams, since that's the fastest path to a channel alert:

<table><thead><tr><th width="151.80975341796875">Target</th><th width="203.3677978515625">Can message</th><th>Credential needed</th><th>Best for</th></tr></thead><tbody><tr><td><code>slack_webhook</code></td><td>A single Slack channel only</td><td>Incoming Webhook URL</td><td>Team-wide alert channel, simplest setup</td></tr><tr><td><code>slack_api</code></td><td>A channel or a specific Slack user</td><td>Slack API token + channel/member ID</td><td>Paging an individual owner directly</td></tr><tr><td><code>teams_webhook</code></td><td>A single Teams channel</td><td>A Teams <strong>Workflows</strong> webhook URL</td><td>Teams-only orgs</td></tr><tr><td><code>smtp</code></td><td>One or more email addresses</td><td>SMTP host, user, password, and sender address</td><td>Recipients without Slack or Teams access, or a distribution list</td></tr></tbody></table>

Use a webhook for channel alerts. Use `slack_api` only to alert a specific person. Use `smtp` when the audience is an email distribution list rather than a chat channel:

```yaml
notification_targets:
  - type: smtp
    notify_on:
      - run_failure
    host: "{{ env_var('SMTP_HOST') }}"
    user: "{{ env_var('SMTP_USER') }}"
    password: "{{ env_var('SMTP_PASSWORD') }}"
    sender: vulcan@example.com
    recipients:
      - data-team@example.com
```

### 2. Get a webhook URL

**Slack:** create an [Incoming Webhook](https://api.slack.com/messaging/webhooks) for the target channel. Copy its unique URL.

<details>

<summary>Set up a Teams Workflows webhook</summary>

The Vulcan reference's own `teams_webhook` example still shows a `webhook.office.com`-style URL (the old "Office 365 Connector" incoming webhook), and that format still works wherever Microsoft hasn't disabled it for your tenant. In practice, many organizations have already been migrated off Office 365 Connectors onto **Workflows**, so check with your Teams admin before assuming either format is available:

1. In the target channel, open **⋯ → Workflows**.
2. Search for and select the **"Send webhook alerts to a channel"** template.
3. Sign in if prompted, confirm the target channel, and add the workflow.
4. Copy the generated URL (a `*.powerplatform.com`/`*.logic.azure.com`-style URL, not `webhook.office.com`).

Either URL format works as the `url` value for a `teams_webhook` target; Vulcan just POSTs to it.

</details>

Do not hardcode webhook URLs in `config.yaml`. Export them as environment variables and use `{{ env_var(...) }}`:

```bash
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
export TEAMS_WEBHOOK_URL=https://your-org.powerplatform.com/.../invoke?...
```

Three other ways to get the value into the process environment, depending on where Vulcan runs:

* **Project `.env` (dev only, gitignored):** Vulcan auto-loads a `.env` file from the project root with no flag needed. Use `--dotenv <path>` only to point at a `.env` file outside the project.
* **Personal machine-wide config:** set an `env_vars` key in `~/.vulcan/config.yaml`. Vulcan loads it before rendering any project config, so every project on that machine picks up the value without per-project setup.
* **CI/CD:** set it as a pipeline secret so it exists only for the job's duration and is never written to disk in the repo.

Before wiring Vulcan at all, confirm the webhook itself works with a direct request. This isolates "is Teams configured right" from "is Vulcan configured right," which is much harder to debug together:

```bash
curl -sS -w "\nHTTP %{http_code}\n" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "attachments": [{
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [{ "type": "TextBlock", "text": "Vulcan webhook test" }]
      }
    }]
  }' \
  "$TEAMS_WEBHOOK_URL"
```

Expect `HTTP 202` and a card in the channel within seconds. If you get a 202 but no card, the workflow's "Post card in a chat or channel" action is likely posting the raw request body as plain text instead of rendering the Adaptive Card. Edit that action to consume the Adaptive Card from the trigger.

### 3. Wire notification\_targets in config.yaml

Add `notification_targets`. This configuration alerts both Slack and Teams on plan and run failures:

{% code title="config.yaml" expandable="true" collapsedlinecount="8" %}

```yaml
notification_targets:
  - type: slack_webhook
    url: "{{ env_var('SLACK_WEBHOOK_URL') }}"
    notify_on:
      - apply_failure
      - run_failure

  - type: teams_webhook
    url: "{{ env_var('TEAMS_WEBHOOK_URL') }}"
    notify_on:
      - apply_failure
      - run_failure
```

{% endcode %}

To page a specific person instead of a channel, use `slack_api` with their Slack member ID as `channel`:

{% code title="config.yaml" expandable="true" collapsedlinecount="7" %}

```yaml
notification_targets:
  - type: slack_api
    token: "{{ env_var('SLACK_API_TOKEN') }}"
    channel: "UXXXXXXXXX"  # channel ID or a user's Slack member ID
    notify_on:
      - run_failure
```

{% endcode %}

{% hint style="info" %}
Field names are **snake\_case**: `notification_targets` and `notify_on`. Vulcan recognizes snake\_case keys only, both here and across config/asset YAML generally; there's no camelCase-to-snake\_case conversion. Use `notification_targets`/`notify_on`, not `notificationTargets`/`notifyOn`.
{% endhint %}

#### The full notify\_on catalog

Each target's `notify_on` list is any combination of these events:

<table data-header-hidden><thead><tr><th width="179.32861328125"></th><th></th></tr></thead><tbody><tr><td><code>notify_on</code> value</td><td>Fires when</td></tr><tr><td><code>apply_start</code></td><td>A plan begins applying to an environment</td></tr><tr><td><code>apply_end</code></td><td>A plan finishes applying to an environment</td></tr><tr><td><code>apply_failure</code></td><td>A plan fails to apply</td></tr><tr><td><code>run_start</code></td><td>A <code>vulcan run</code> begins</td></tr><tr><td><code>run_end</code></td><td>A <code>vulcan run</code> finishes</td></tr><tr><td><code>run_failure</code></td><td>A <code>vulcan run</code> fails</td></tr><tr><td><code>dq_start</code></td><td>Data quality checks begin</td></tr><tr><td><code>dq_end</code></td><td>Data quality checks finish</td></tr></tbody></table>

For a routine failure channel, `apply_failure` and `run_failure` are usually enough. `*_start`/`*_end` are useful for a busier "activity feed" style channel but fire on every plan and run, not just problems.

Older Vulcan builds used `check_start`/`check_end`/`check_failure` instead of today's `dq_start`/`dq_end`/`dq_failure`. If a project's config or a notification handler still references `check_*`, migrate it to the `dq_*` names.

#### Global targets vs. per-user targets

A top-level `notification_targets` key applies project-wide. A target under a user in `users` alerts that user too. Use it to page an owner without routing every failure to them.

{% code title="config.yaml" expandable="true" collapsedlinecount="8" %}

```yaml
# Everyone gets these
notification_targets:
  - type: slack_webhook
    url: "{{ env_var('SLACK_WEBHOOK_URL') }}"
    notify_on:
      - apply_failure
      - run_failure

# This user additionally gets a direct page on run failures
users:
  - username: alex
    notification_targets:
      - type: slack_api
        token: "{{ env_var('SLACK_API_TOKEN') }}"
        channel: "U01ALEXID"
        notify_on:
          - run_failure
```

{% endcode %}

A global target fires for every matching event regardless of who owns the failing model. A user-specific target fires in addition to the global ones, so use it when one person needs a direct page on top of the channel alert.

#### Keep local dev from spamming the channel

Set a top-level `username` key (in the project `config.yaml` or in `~/.vulcan/config.yaml`) to route **every** notification to only that user's personal targets while you're iterating:

```yaml
username: alex
```

Putting it in `~/.vulcan/config.yaml` is the better spot for this, since it only silences notifications on your machine and doesn't affect anyone else's config.

### 4. Publish, then confirm a real failure arrives

Verify notifications against a published product. First publish cleanly. Then introduce a realistic failure and confirm delivery.

The most reproducible failure is a model that cannot build. Point a model at a column that doesn't exist, for example, an `orders-analytics`-style model tracking order counts per item:

```sql
MODEL (
  name vulcan_example.full_model,
  kind FULL,
  cron '@daily',
);

SELECT
  item_id,
  count(distinct order_id) AS num_orders,
FROM
  vulcan_example.incremental_model
GROUP BY item_id
```

The upstream model has no `order_id` column, so the apply fails instead of the model building.

Run a plan against `prod`:

```bash
vulcan plan prod --select-model "vulcan_example.full_model" --auto-apply
```

`vulcan plan` reports the failure. Within seconds, the webhook channel receives a message from the unedited **default** `teams_webhook` template.

The header line is a status icon plus the raw event name: `❌ apply_failure` for a failure, `✅ apply_end` for a clean success, `⚠️` for a warning, `ℹ️` for an info-level start/end event. The Python exception or error text follows below the summary; any single text block over 3000 characters gets truncated with `...`. This is accurate but harder to scan. After confirming delivery, restore the correct column and re-run the plan.

### 5. Run as a managed DataOS resource (optional)

If this Vulcan project runs as a managed DataOS `vulcan` resource rather than from a shell, don't hand-manage `TEAMS_WEBHOOK_URL` at all: put it in a DataOS **Secret** and inject it via a **projection**, the same pattern used for depot and Nilus connector credentials.

{% hint style="warning" %}
This block follows DataOS's general Secret/Projection pattern rather than a Vulcan-specific worked example. Deployment for a managed `vulcan` resource is driven by a `deployment:` block in `config.yaml`, rendered into the resource manifest by `vulcan create_deploy_yaml`; there's no separate manifest to hand-edit `spec.use` into. Confirm the projection lands in the environment `create_deploy_yaml` renders before deploying.
{% endhint %}

```yaml
name: teams-webhook
version: v2alpha
type: secret
layer: user
secret:
  type: key-value
  data:
    TEAMS_WEBHOOK_URL: "https://your-org.powerplatform.com/.../invoke?..."
```

```yaml
deployment:
  use:
    secrets:
      - { id: <tenant>:teams-webhook, context_alias: teams_webhook }
    env_vars:
      - key: TEAMS_WEBHOOK_URL
        template: "{{ secrets['teams_webhook'].TEAMS_WEBHOOK_URL }}"
```

Once that lands in the container's environment, `{{ env_var('TEAMS_WEBHOOK_URL') }}` in `config.yaml` resolves it exactly the way a shell export would. The projection is just how the value gets into the process before Vulcan starts.

## Troubleshooting

| Symptom                                                   | Likely cause                                                                                     | Fix                                                                                               |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `ConfigError: Missing Teams webhook URL for notification` | Neither `url` on the target nor `TEAMS_WEBHOOK_URL` in the environment is set                    | Set `url` explicitly, or export `TEAMS_WEBHOOK_URL` in the environment Vulcan runs in             |
| `curl` test returns HTTP 400                              | Malformed JSON, or an escaped `\?` in the copied webhook URL                                     | Re-copy the URL as one unescaped string and retest                                                |
| `curl` test returns HTTP 401/403                          | The Teams workflow URL expired or was revoked                                                    | Regenerate the workflow and update `TEAMS_WEBHOOK_URL` everywhere it's set                        |
| `curl` succeeds (202) but nothing shows in the channel    | The workflow is posting the raw body as text instead of rendering the Adaptive Card              | Edit the workflow's post action to consume the Adaptive Card from the trigger                     |
| Notification never fires on a real failure                | The event isn't in `notify_on`, or `type: teams_webhook` isn't recognized by this Vulcan version | Add the missing event; confirm the Vulcan version supports `teams_webhook` (see Before you begin) |

## References

* [Notifications](https://v2.dataos.info/references/resources/vulcan/configurations/notifications) - Vulcan's notification target and event reference.
* [Secret manifest configuration](https://v2.dataos.info/references/resources/secret/manifest-configuration) - full `type: secret` manifest reference.
* [Secrets and projections](https://v2.dataos.info/references/resources/nilus/concepts/secrets-and-projections) - the general DataOS pattern for injecting a Secret into a running resource.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/build/july2026/recipes/route-failures-to-slack-or-teams.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
