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

# Notifiers for alert destinations

> Point Alerts and budget alerts at email, Slack, or a generic webhook by creating one reusable Notifier per destination.

See [HTTP URLs and authentication](/docs/reference/base-urls.md) and the API reference for complete request and response formats.

**Use Cases**

* Sending threshold alerts to an on-call address.
* Posting a budget threshold into a Slack channel.
* Forwarding alert payloads into an incident tool through a generic webhook.

***

## Overview

A **Notifier** is a reusable destination that [**Alerts**](/docs/ai-studio/observability/alerts.md) deliver to. One **Notifier** carries one channel and any number of **Alerts** can select it, so a destination is configured once and shared.

Three channels are available: **Email**, **Slack** through an incoming webhook, and a generic **Webhook**.

## Channels

| Channel | `type` | Destination field | Notes |
| - | - | - | - |
| Email | `NOTIFIER_TYPE_EMAIL` | `emails` | One or more addresses. Duplicates and surrounding whitespace are removed, and each address is validated. |
| Slack | `NOTIFIER_TYPE_SLACK_WEBHOOK` | `incoming_webhook_url` | A Slack incoming webhook URL. |
| Webhook | `NOTIFIER_TYPE_WEBHOOK` | `webhook_url` | Any absolute HTTPS URL, with optional request headers. |

Both webhook URLs must be absolute HTTPS URLs. A plain `http://` URL is rejected with the offending field named, either `webhook_url must be an absolute HTTPS URL` or `incoming_webhook_url must be an absolute HTTPS URL`.

## Create a notifier

> [tab] AI Studio
>
> Open **Settings** > **Notifiers** and select <kbd> Notifier</kbd> to open the sheet. A new one can also be created from the **Alert** form without leaving it.
>
> **1. Name the notifier**
>
> Enter a **Name** of up to 255 characters.
>
> **2. Choose a channel**
>
> Select **Send via**, then fill the destination the channel asks for: recipient addresses, a Slack incoming webhook URL, or a webhook URL with optional headers.
>
> **3. Save**
>
> Choose **Create**. The button stays disabled until the name and a valid destination are present.

> [tab] API & SDK
>
> ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X POST https://router.toqan.ai/eu/v2/notifiers \
>   -H "Authorization: Bearer $TOQAN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "display_name": "On-call email",
>     "type": "NOTIFIER_TYPE_EMAIL",
>     "emails": ["oncall@example.com"]
>   }'
> ```
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "notifier": {
>     "_id": "notifier_01m48465jqdz12asrmg7g7qcw7",
>     "display_name": "On-call email",
>     "type": "NOTIFIER_TYPE_EMAIL",
>     "emails": ["oncall@example.com"],
>     "project_id": "",
>     "created_at": "2026-10-06T08:09:54.519Z"
>   }
> }
> ```
>
> **Parameters**
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `display_name` | string | Yes | Name shown wherever the notifier is selected. Up to 255 characters. |
> | `type` | enum | Yes | `NOTIFIER_TYPE_EMAIL`, `NOTIFIER_TYPE_SLACK_WEBHOOK`, or `NOTIFIER_TYPE_WEBHOOK`. |
> | `emails` | string array | For email | Recipient addresses. Required when the type is email. |
> | `incoming_webhook_url` | string | For Slack | Absolute HTTPS URL. Required when the type is Slack. |
> | `webhook_url` | string | For webhook | Absolute HTTPS URL. Required when the type is a generic webhook. |
> | `headers` | object | No | Request headers for a generic webhook. See [Secret headers](#secret-headers). |
> | `project_id` | string | No | Scope the notifier to one **Project**. Omitted means workspace-wide. A project-scoped API key always creates in its own project. |
> | `metadata` | object | No | Custom JSON stored with the notifier. |
>
> > [!NOTE]
> >
> > The wire field is `_id`; the SDKs expose the same value as `id`.

## Manage notifiers

> [tab] AI Studio
>
> The **Notifiers** list shows each one with its **Name**, **Destination**, **Type**, and last update, and supports search by name, a type filter, and page sizes of 25, 50, or 100.
>
> Open the row menu to edit or delete one. A **Notifier** that an **Alert** or a budget alert still selects cannot be deleted: the API refuses with `Notifier is in use and cannot be deleted.` Remove it from those alerts first.

> [tab] API & SDK
>
> | Operation | Endpoint |
> | - | - |
> | [Create a notifier](/docs/reference/notifiers/create-a-notifier.md) | `POST /v2/notifiers` |
> | [List notifiers](/docs/reference/notifiers/list-notifiers.md) | `GET /v2/notifiers` |
> | [Retrieve a notifier](/docs/reference/notifiers/retrieve-a-notifier.md) | `GET /v2/notifiers/{notifier_id}` |
> | [Update a notifier](/docs/reference/notifiers/update-a-notifier.md) | `PATCH /v2/notifiers/{notifier_id}` |
> | [Delete a notifier](/docs/reference/notifiers/delete-a-notifier.md) | `DELETE /v2/notifiers/{notifier_id}` |
>
> `GET /v2/notifiers` accepts `search` for a case-insensitive match on the name, `type` to restrict the result to one or more channels, and `project_id`, and pages with `starting_after` and `ending_before`.

## Where notifiers are used

| Surface | How the notifier is attached |
| - | - |
| [**Alerts**](/docs/ai-studio/observability/alerts.md) | Selected under **Notify via** in the **Alert** form, which allows several and can create one inline. That page covers the cap and what happens to an **Alert** with none. |
| [**Budget alerts**](/docs/ai-gateway/budgets.md) | On a budget threshold, where at least one **Notifier** is required. |
| **Monitors** | **Create alert** on a widget opens the [**Alerts**](/docs/ai-studio/observability/alerts.md) form with the widget's metric, so the same notifier selection applies. |

## Terraform

The provider manages notifiers with the `orq_notifier` resource, and `notifier_ids` attaches them to a budget alert or an alert rule. See Terraform quickstart and Importing resources.

## Secret headers

A generic webhook can carry request headers. A header value is either a plain string or an object that marks it secret:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "headers": {
    "Authorization": { "secret": true, "value": "Bearer sk-live-..." },
    "X-Source": "toqan"
  }
}
```

A header marked `{"secret": true}` comes back empty on read and stays readable nowhere, unlike a plain header. For the full list of what each storage class protects, see Secrets.

## Send notifications to a Microsoft Teams channel

Route alert notifications to a **Microsoft Teams** channel with a generic webhook **Notifier**. Teams renders messages in its own card format while **Toqan Router** sends a JSON envelope, so the webhook points at a small relay that converts the payload before forwarding it. The [Microsoft Teams example](/docs/ai-gateway/budgets.md#send-notifications-to-a-microsoft-teams-channel) covers the Teams workflow, the relay, and attaching the notifier to an alert.

## Limitations

| Limitation | Impact | Workaround |
| - | - | - |
| One channel per notifier | A destination that should receive both email and Slack needs two notifiers | Create one per channel and select both on the alert |
| No delivery log | The notifier record does not show what it sent | Check the receiving channel, or use a webhook endpoint that logs requests |
| Deletion is refused while in use | A notifier an **Alert** or budget alert still selects cannot be deleted | Remove it from those alerts, then delete it |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.