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

# Create notification channel

> Create a new delivery channel for receiving platform event notifications.

<Warning>
  The `secret` field is write-only and is not returned by the API after creation. To change it later, use the [update channel endpoint](/api-reference/api/notification/update-notification-channel) instead.
</Warning>

## Body

<ParamField body="channel_type" type="string" required>
  Channel type: `webhook` or `email`.

  For more information, see [Webhooks](/api-reference/webhooks) and [Email notifications](/api-reference/email).
</ParamField>

<ParamField body="event_types" type="array" required>
  Event types to subscribe to.

  | Value             | Description                                           |
  | ----------------- | ----------------------------------------------------- |
  | `job.scheduled`   | Job queued to run                                     |
  | `job.in_progress` | Job has started                                       |
  | `job.completed`   | Job finished processing                               |
  | `job.stopped`     | Job has stopped                                       |
  | `job.failed`      | Job failed to initialize without processing any files |
</ParamField>

<ParamField body="description" type="string">
  Channel description. Maximum 255 characters.
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the channel is active. Default: `true`.
</ParamField>

<ParamField body="url" type="string">
  Webhook endpoint URL. Must use HTTPS. Required when `channel_type` is `webhook`.
</ParamField>

<ParamField body="secret" type="string">
  Signing secret for verifying incoming webhook requests. Must be  between24 and 75 bytes (24 to 75 ASCII characters). Applies when `channel_type` is `webhook`.

  Use this secret to [verify incoming webhook requests](/api-reference/webhooks#verify-webhook-requests). If you do not provide a secret, you cannot use secret-based verification for incoming webhook requests.

  <Note>
    The secret is write-only and is not returned by the API after creation. To change it later, use the [update channel endpoint](/api-reference/api/notification/update-notification-channel) instead.
  </Note>
</ParamField>

<ParamField body="email_config" type="object">
  Email delivery configuration. Required when `channel_type` is `email`.

  | Value             | Required | Description                                                                  |
  | ----------------- | -------- | ---------------------------------------------------------------------------- |
  | `recipient_email` | yes      | Email address to deliver notifications to.                                   |
  | `reply_to`        |          | Email address set as the reply-to header in notification emails.             |
  | `cc`              |          | Additional email addresses to copy on notification emails. Array of strings. |
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Unique identifier for the channel.
</ResponseField>

<ResponseField name="channel_type" type="string" required>
  Channel type: `webhook` or `email`.
</ResponseField>

<ResponseField name="event_types" type="array" required>
  Subscribed event types.
</ResponseField>

<ResponseField name="enabled" type="boolean" required>
  Whether the channel is active.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the channel was created.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp when the channel was last updated.
</ResponseField>

<ResponseField name="description" type="string">
  Channel description.
</ResponseField>

<ResponseField name="url" type="string">
  Webhook endpoint URL. Present when `channel_type` is `webhook`.
</ResponseField>

<ResponseField name="email_config" type="object">
  Email delivery configuration. Present when `channel_type` is `email`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "${UNSTRUCTURED_API_URL}/api/v1/notifications/channels" \
    --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
    --header "Content-Type: application/json" \
    --data '{
      "channel_type": "webhook",
      "url": "https://hooks.example.com/notify",
      "event_types": ["job.completed", "job.failed"],
      "description": "Job status alerts",
      "enabled": true
    }'
  ```

  ```python Python SDK theme={null}
  import os
  from unstructured_client import UnstructuredClient
  from unstructured_client.models.operations import CreateChannelApiV1NotificationsChannelsPostRequest

  client = UnstructuredClient(
      api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"),
      server_url=os.getenv("UNSTRUCTURED_API_URL"),
  )

  response = client.notifications.create_channel(
      request=CreateChannelApiV1NotificationsChannelsPostRequest(
          channel_type="webhook",
          url="https://hooks.example.com/notify",
          event_types=["job.completed", "job.failed"],
          description="Job status alerts",
          enabled=True,
      )
  )
  print(response)
  ```

  ```python Python SDK (async) theme={null}
  import asyncio
  import os
  from unstructured_client import UnstructuredClient
  from unstructured_client.models.operations import CreateChannelApiV1NotificationsChannelsPostRequest

  async def create_channel():
      client = UnstructuredClient(
          api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"),
          server_url=os.getenv("UNSTRUCTURED_API_URL"),
      )
      response = await client.notifications.create_channel_async(
          request=CreateChannelApiV1NotificationsChannelsPostRequest(
              channel_type="webhook",
              url="https://hooks.example.com/notify",
              event_types=["job.completed", "job.failed"],
              description="Job status alerts",
              enabled=True,
          )
      )
      print(response)

  asyncio.run(create_channel())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "channel_type": "webhook",
    "description": "Job status alerts",
    "event_types": ["job.completed", "job.failed"],
    "enabled": true,
    "url": "https://hooks.example.com/notify",
    "created_at": "2026-04-29T10:00:00Z",
    "updated_at": "2026-04-29T10:00:00Z"
  }
  ```
</ResponseExample>