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

# Create a notification channel

> Register an https destination that monitors post to when they fire

export const MonitorsExperimental = () => <Warning>
    <strong>Monitors is experimental.</strong> Request and payload shapes can change without a deprecation window. Monitors isn't recommended for production workflows.
  </Warning>;

<MonitorsExperimental />

## Notes

* To authenticate, you'll need a [Tako API key](https://tako.com/console/api-keys). It's best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
* Create the channel before the monitor that uses it. [Create a monitor](/api-reference/monitors-create) returns `404` for a `channel_ids` entry you don't own.
* `url` must use `https`, on port 443 or 8443, and must resolve to a public address. See [What Tako accepts as a URL](/documentation/integrating-tako/monitors/webhook-deliveries#what-tako-accepts-as-a-url).
* A channel starts `active`. After 2 consecutive failed deliveries, Tako pauses it. See [Pause or resume a notification channel](/api-reference/notification-channels-update).
* You can hold a limited number of channels, counted per user rather than pooled across an account. When you're at that limit, this endpoint returns `400` with `error_type: LIMIT_REACHED` and a `limit` giving your cap. Delete a channel you no longer need, or contact [support@tako.com](mailto:support@tako.com) about an enterprise limit.
* For the request Tako posts to this channel, see [Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries).

<Warning>
  **Store `secret` when you read the `201` response.** No later request returns it. Tako signs every delivery to this channel with it, so if you lose it, delete the channel and create a new one.
</Warning>

## Choosing a `kind`

`kind` decides how Tako shapes the request body it posts:

* `webhook`, the default: nested JSON that namespaces the monitor, the firing, and the payload.
* `slack_workflow`: a flat body of strings, for a Slack Workflow Builder trigger, which rejects nested values.

For both shapes, see [Webhook deliveries](/documentation/integrating-tako/monitors/webhook-deliveries).


## OpenAPI

````yaml POST /v1/notification_channels
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/notification_channels:
    post:
      tags:
        - monitors
      summary: Create a notification channel
      description: >-
        Register an https destination that monitors post to when they fire. The
        response includes a signing secret that Tako generates. Store it when
        you read the response, because no later request returns it.


        **Experimental.** Request and payload shapes can change without a
        deprecation window. Monitors isn't recommended for production workflows.
      operationId: createNotificationChannel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelCreate'
        required: true
      responses:
        '201':
          description: >-
            The new channel, including the signing secret that only this
            response returns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelCreated'
        '400':
          description: >-
            Invalid request, or you've reached your notification channel limit.
            The error_type is LIMIT_REACHED, and limit is the cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorCreateRejected'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
        - apiKey: []
components:
  schemas:
    NotificationChannelCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        kind:
          $ref: '#/components/schemas/ChannelKind'
          description: >-
            How Tako shapes the body it posts. Use slack_workflow for a Slack
            Workflow Builder trigger, which rejects nested values.
          default: webhook
        url:
          type: string
          maxLength: 2048
          format: uri
          title: Url
          description: >-
            The https destination that Tako posts to. Tako rejects http, a URL
            that embeds credentials, and a host that resolves to a private or
            loopback address.
      type: object
      required:
        - name
        - url
      title: NotificationChannelCreate
    NotificationChannelCreated:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        kind:
          $ref: '#/components/schemas/ChannelKind'
        url:
          type: string
          title: Url
        status:
          $ref: '#/components/schemas/ChannelStatus'
        status_reason:
          anyOf:
            - $ref: '#/components/schemas/ChannelStatusReason'
            - type: 'null'
          description: >-
            Why Tako paused the channel. Null while the channel is active, and
            null when you paused it yourself.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        secret:
          type: string
          title: Secret
          description: >-
            The signing secret for this channel. Store it now, because this
            response is the only place it appears and no later request returns
            it. Tako signs every delivery to this channel with it.
      type: object
      required:
        - id
        - name
        - kind
        - url
        - status
        - status_reason
        - created_at
        - updated_at
        - secret
      title: NotificationChannelCreated
    MonitorCreateRejected:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/MonitorCreateErrorType'
        candidates:
          items:
            additionalProperties:
              $ref: '#/components/schemas/Scalar'
            type: object
          type: array
          title: Candidates
          default: []
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
      type: object
      required:
        - error_message
        - error_type
      title: MonitorCreateRejected
      description: >-
        The 400 response from createMonitor, createNotificationChannel, and
        patchMonitor. When

        error_type is AMBIGUOUS_SUBJECT, candidates lists every subject the
        parameters could have

        matched, best first, so you can narrow them and retry. When error_type
        is LIMIT_REACHED,

        limit is how many active monitors or notification channels you may hold.
        Tako counts that

        limit per user rather than pooling it across an account, and the message
        says how to free

        one, or where to ask for an enterprise limit. For any other error_type,
        candidates is empty

        and limit is null.
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
        - error_message
        - error_type
      title: BaseAPIError
    ChannelKind:
      type: string
      enum:
        - webhook
        - slack_workflow
      title: ChannelKind
      description: >-
        How Tako shapes the request body it posts to a channel. `webhook` sends
        nested JSON that namespaces the monitor, the firing, and the payload.
        `slack_workflow` sends a flat body of strings for a Slack Workflow
        Builder trigger, which rejects any nested value.
    ChannelStatus:
      type: string
      enum:
        - active
        - paused
      title: ChannelStatus
    ChannelStatusReason:
      type: string
      enum:
        - delivery_failures
      title: ChannelStatusReason
    MonitorCreateErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AMBIGUOUS_SUBJECT
        - LIMIT_REACHED
      title: MonitorCreateErrorType
      description: Why a monitors operation refused the request.
    Scalar:
      anyOf:
        - type: string
        - type: integer
        - type: number
        - type: boolean
        - type: 'null'
    APIErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AUTHENTICATION_ERROR
        - INTERNAL_SERVER_ERROR
        - RELEVANT_RESULTS_NOT_FOUND
        - RATE_LIMIT_EXCEEDED
        - PAYMENT_REQUIRED
        - REQUEST_TIMEOUT
        - FORBIDDEN
        - NOT_FOUND
        - SERVICE_UNAVAILABLE
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
        - PLACEHOLDER_CARD
        - VARIABLE_COST_NOT_REQUESTED
      title: APIErrorType
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````

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