curl --request POST \
--url "${UNSTRUCTURED_API_URL}/api/v1/workflows/f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c/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
}'
{
"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"
}
Workflow
Create workflow notification channel
Create a new delivery channel for receiving platform event notifications scoped to the specified workflow.
POST
/
api
/
v1
/
workflows
/
{workflow_id}
/
notifications
/
channels
curl --request POST \
--url "${UNSTRUCTURED_API_URL}/api/v1/workflows/f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c/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
}'
{
"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"
}
The
secret field is write-only and is not returned by the API after creation. To change it later, use the update workflow notification channel endpoint instead.Path parameters
string
required
The unique identifier of the workflow.
Body
string
required
Channel type:
webhook or email.For more information, see Webhooks and Email notifications.array
required
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 |
string
Channel description. Maximum 255 characters.
boolean
Whether the channel is active. Default:
true.string
Webhook endpoint URL. Must use HTTPS. Required when
channel_type is webhook.string
Signing secret for verifying incoming webhook requests. Must be between 24 and 75 bytes. Applies when
channel_type is webhook.Use this secret to verify incoming webhook requests. If you do not provide a secret, you cannot use secret-based verification for incoming webhook requests.The secret is write-only and is not returned by the API after creation. To change it later, use the update workflow notification channel endpoint instead.
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. |
Response
string
required
Unique identifier for the channel.
string
required
Channel type:
webhook or email.array
required
Subscribed event types.
boolean
required
Whether the channel is active.
string
required
ISO 8601 timestamp when the channel was created.
string
required
ISO 8601 timestamp when the channel was last updated.
string
Channel description.
string
Webhook endpoint URL. Present when
channel_type is webhook.object
Email delivery configuration. Present when
channel_type is email.curl --request POST \
--url "${UNSTRUCTURED_API_URL}/api/v1/workflows/f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c/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
}'
{
"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"
}
Was this page helpful?