Update notification channel

Update workspace-scoped notification channel. Only provided fields are updated.

PATCH /api/v1/notifications/channels/{channel_id}

cURL

curl --request PATCH \
  --url "${UNSTRUCTURED_API_URL}/api/v1/notifications/channels/c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f" \
  --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "event_types": ["job.completed", "job.failed", "job.in_progress"],
    "enabled": true
  }'

Response

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

Channels that have not been verified cannot be updated.

Path parameters

channel_id · string · required

The unique identifier of the notification channel to update.

Body

channel_type · string

The existing channel type: webhook or email. This field is immutable. If provided, it must match the channel’s current type.

description · string

Updated channel description. Maximum 255 characters.

event_types · array

Updated list of event types to subscribe to.

Value	Description
job.scheduled	Job queued to run
job.in_progress	Job has started
job.progress	Job has reached approximately 25% progress
job.completed	Job finished processing
job.stopped	Job has stopped
job.failed	Job failed to initialize without processing any files

enabled · boolean

Whether the channel is active.

url · string

Updated webhook endpoint URL. Applies when channel_type is webhook.

secret · string

Updated signing secret for verifying incoming webhook requests. Must be between 24 and 75 bytes. Applies when channel_type is webhook. Omit to keep the current value, or pass an empty string to remove the custom secret.

Use this secret to verify incoming webhook requests.

email_config · object

Updated email delivery configuration. Applies 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.

Response

id · string · required

Unique identifier for the channel.

channel_type · string · required

Channel type: webhook or email.

event_types · array · required

Subscribed event types.

enabled · boolean · required

Whether the channel is active.

created_at · string · required

ISO 8601 timestamp when the channel was created.

updated_at · string · required

ISO 8601 timestamp when the channel was last updated.

description · string

Channel description.

url · string

Webhook endpoint URL. Present when channel_type is webhook.

email_config · object

Email delivery configuration. Present when channel_type is email.

cURL

curl --request PATCH \
  --url "${UNSTRUCTURED_API_URL}/api/v1/notifications/channels/c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f" \
  --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "event_types": ["job.completed", "job.failed", "job.in_progress"],
    "enabled": true
  }'

Response

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