---
title: "Create a notifier"
method: POST
path: "/v2/notifiers"
tags: ["Notifiers"]
---

# Create a notifier

`POST /v2/notifiers`

Creates a notifier destination in a project. Choose `NOTIFIER_TYPE_EMAIL`, `NOTIFIER_TYPE_SLACK_WEBHOOK`, or `NOTIFIER_TYPE_WEBHOOK` and provide the matching destination fields.

## Request body

- union — Create notifier request. `project_id`, `display_name`, and `type` are always required. The destination field required by `type` is captured in `oneOf`.
  - object — `emails` is required when `type` is `NOTIFIER_TYPE_EMAIL`.
    - `project_id` string — Optional. Workspace-scoped callers may set this to create a project-scoped notifier, or omit it for a workspace-wide notifier. Project-scoped API keys create in the API key's project.
    - `display_name` string, required — Required. Human-readable notifier name.
    - `metadata` object — Optional. Custom JSON metadata stored with the notifier.
    - `type` 'NOTIFIER_TYPE_EMAIL', required
    - `emails` string[], required — Required when `type` is `NOTIFIER_TYPE_EMAIL`. Omit for other notifier types.
    - `incoming_webhook_url` string — Required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`. Omit for other notifier types.
    - `webhook_url` string — Required when `type` is `NOTIFIER_TYPE_WEBHOOK`. Omit for other notifier types.
    - `headers` object — Optional generic webhook headers. Each value may be a string or `{ "secret": true, "value": "..." }`.
  - object — `incoming_webhook_url` is required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`.
    - `project_id` string — Optional. Workspace-scoped callers may set this to create a project-scoped notifier, or omit it for a workspace-wide notifier. Project-scoped API keys create in the API key's project.
    - `display_name` string, required — Required. Human-readable notifier name.
    - `metadata` object — Optional. Custom JSON metadata stored with the notifier.
    - `type` 'NOTIFIER_TYPE_SLACK_WEBHOOK', required
    - `emails` string[] — Required when `type` is `NOTIFIER_TYPE_EMAIL`. Omit for other notifier types.
    - `incoming_webhook_url` string, required — Required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`. Omit for other notifier types.
    - `webhook_url` string — Required when `type` is `NOTIFIER_TYPE_WEBHOOK`. Omit for other notifier types.
    - `headers` object — Optional generic webhook headers. Each value may be a string or `{ "secret": true, "value": "..." }`.
  - object — `webhook_url` is required when `type` is `NOTIFIER_TYPE_WEBHOOK`; `headers` is optional.
    - `project_id` string — Optional. Workspace-scoped callers may set this to create a project-scoped notifier, or omit it for a workspace-wide notifier. Project-scoped API keys create in the API key's project.
    - `display_name` string, required — Required. Human-readable notifier name.
    - `metadata` object — Optional. Custom JSON metadata stored with the notifier.
    - `type` 'NOTIFIER_TYPE_WEBHOOK', required
    - `emails` string[] — Required when `type` is `NOTIFIER_TYPE_EMAIL`. Omit for other notifier types.
    - `incoming_webhook_url` string — Required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`. Omit for other notifier types.
    - `webhook_url` string, required — Required when `type` is `NOTIFIER_TYPE_WEBHOOK`. Omit for other notifier types.
    - `headers` object — Optional generic webhook headers. Each value may be a string or `{ "secret": true, "value": "..." }`.

## Response `200`

OK

- CreateNotifierResponse
  - `notifier` union, required — Notifier resource. The destination field present on the resource depends on `type` and is captured in `oneOf`.
    - object — `emails` is present for email notifiers.
      - `_id` string, required — Unique notifier identifier assigned by ORQ.
      - `project_id` string — Project that contains the notifier. Empty for workspace-wide notifiers.
      - `display_name` string, required — Human-readable notifier name.
      - `created_at` string, date-time, required — Time when the notifier was created.
      - `updated_at` string, date-time, required — Time when the notifier was last updated.
      - `created_by_id` string — User ID that created the notifier.
      - `updated_by_id` string — User ID that last updated the notifier.
      - `metadata` object — Custom JSON metadata stored with the notifier.
      - `type` 'NOTIFIER_TYPE_EMAIL', required
      - `emails` string[], required — Email addresses notified when `type` is `NOTIFIER_TYPE_EMAIL`.
      - `incoming_webhook_url` string — Slack incoming webhook URL used when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`.
      - `webhook_url` string — Generic webhook URL used when `type` is `NOTIFIER_TYPE_WEBHOOK`.
      - `headers` object — Optional HTTP headers for generic webhooks. Each entry may be a string value or an object with `secret` and `value`.
    - object — `incoming_webhook_url` is present for Slack webhook notifiers.
      - `_id` string, required — Unique notifier identifier assigned by ORQ.
      - `project_id` string — Project that contains the notifier. Empty for workspace-wide notifiers.
      - `display_name` string, required — Human-readable notifier name.
      - `created_at` string, date-time, required — Time when the notifier was created.
      - `updated_at` string, date-time, required — Time when the notifier was last updated.
      - `created_by_id` string — User ID that created the notifier.
      - `updated_by_id` string — User ID that last updated the notifier.
      - `metadata` object — Custom JSON metadata stored with the notifier.
      - `type` 'NOTIFIER_TYPE_SLACK_WEBHOOK', required
      - `emails` string[] — Email addresses notified when `type` is `NOTIFIER_TYPE_EMAIL`.
      - `incoming_webhook_url` string, required — Slack incoming webhook URL used when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`.
      - `webhook_url` string — Generic webhook URL used when `type` is `NOTIFIER_TYPE_WEBHOOK`.
      - `headers` object — Optional HTTP headers for generic webhooks. Each entry may be a string value or an object with `secret` and `value`.
    - object — `webhook_url` is present for generic webhook notifiers; `headers` is optional.
      - `_id` string, required — Unique notifier identifier assigned by ORQ.
      - `project_id` string — Project that contains the notifier. Empty for workspace-wide notifiers.
      - `display_name` string, required — Human-readable notifier name.
      - `created_at` string, date-time, required — Time when the notifier was created.
      - `updated_at` string, date-time, required — Time when the notifier was last updated.
      - `created_by_id` string — User ID that created the notifier.
      - `updated_by_id` string — User ID that last updated the notifier.
      - `metadata` object — Custom JSON metadata stored with the notifier.
      - `type` 'NOTIFIER_TYPE_WEBHOOK', required
      - `emails` string[] — Email addresses notified when `type` is `NOTIFIER_TYPE_EMAIL`.
      - `incoming_webhook_url` string — Slack incoming webhook URL used when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`.
      - `webhook_url` string, required — Generic webhook URL used when `type` is `NOTIFIER_TYPE_WEBHOOK`.
      - `headers` object — Optional HTTP headers for generic webhooks. Each entry may be a string value or an object with `secret` and `value`.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/1acdf0c4a90a/schema)