From afbc157811479c0ae53ed17f33b22b8b513779c0 Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Mon, 12 Jan 2026 08:16:11 -0800 Subject: [PATCH 1/4] Webhooks --- snippets/examples/webhooks.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 snippets/examples/webhooks.mdx diff --git a/snippets/examples/webhooks.mdx b/snippets/examples/webhooks.mdx new file mode 100644 index 00000000..bd9b9c02 --- /dev/null +++ b/snippets/examples/webhooks.mdx @@ -0,0 +1,22 @@ +## Webhook examples + + +### Zapier + + +1. [Sign up for Zapier](https://zapier.com/sign-up), if you don't already have an account. +2. [Log in to your Zapier account](https://zapier.com/app/login), if you aren't already logged in. +3. On the sidebar, click **Create > Zaps**. +4. In the designer, click **Trigger: Select the event that starts your Zap**. +5. In the dialog, with **Home** selected in the sidebar, under **Popular built-in tools**, click **Webhooks**. +6. In the settings pane on the right, for **Trigger event**, select **Catch Raw Hook**. + + +### Slack + + +### Webhook.site + + + +### Beeceptor \ No newline at end of file From 67f9cba259a52a246f7969be2385a168006586a0 Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Fri, 6 Feb 2026 17:41:55 -0800 Subject: [PATCH 2/4] Begin adding webhooks call examples for curl and Postman --- api-reference/webhooks.mdx | 164 ++++++++++++++++++ docs.json | 3 +- .../get-started-api-url-only.mdx | 24 +++ 3 files changed, 190 insertions(+), 1 deletion(-) create mode 100644 api-reference/webhooks.mdx create mode 100644 snippets/general-shared-text/get-started-api-url-only.mdx diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx new file mode 100644 index 00000000..a0cc64df --- /dev/null +++ b/api-reference/webhooks.mdx @@ -0,0 +1,164 @@ +--- +title: Webhooks +--- + +A _webhook_ is a way for a _sender_ (also sometimes called a _source_, _provider_, _producer_, or _sender +application_) to send data to a _receiver_ (also sometimes called a _destination_, _consumer_, +_receiver application_, or simply an _endpoint_). For Unstructured webhooks, Unstructured is the sender, +and your solution is the receiver. Some popular receivers include +[AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/urls-webhook-tutorial.html), +[Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-bindings-http-webhook), +[Google Cloud Run](https://docs.cloud.google.com/run/docs/triggering/webhooks), +[Zapier](https://zapier.com/blog/what-are-webhooks/), +[Slack](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/), +[Svix](https://svix.com), and +[Webhook.site](https://webhook.site/). + +The receiver provides a unique URL (often called the +_webhook URL_, _callback URL_, or _notification URL_), to receive the data from Unstructured. +Unstructured calls the webhook URL by using an HTTP POST operation and +passes a payload of data to the receiver in JSON format. The receiver then processes the payload and can decide +what to do with the data from there. + +Because webhooks are event-driven, something must first happen to trigger the webhook. In +Unstructured, these webhooks can be triggered whenever a [job](/api-reference/workflow/jobs) that is associated with its target [workflow](/api-reference/workflow/workflows) does +one or more of the following: + +- Is scheduled (programmatically, an event type of `job.scheduled`) +- Begins its work (`job.in_progress`) +- Has stopped (`job.stopped`) +- Fails (`job.failed`) +- Is completed (`job.completed`) + +When a webhook is configured to deliver event-driven notification data payloads from a sender to a receiver, this configuration +is called a _notification channel_. For Unstructured webhooks, notification channels can be created and managed at the following levels: + +- At the account level, known as an _account-scoped notification channel_. This allows any job that is associated with any + workflow in the account to trigger the webhook. This can be useful for example for routing pager requests to a team of on-call engineers in an + IT operations center whenever any job fails across the organization. +- At the workflow level, known as _workflow-scoped notification channels_. This allows any job that is associated only with + the target workflow to trigger the webhook. This can be useful for example for emailing a department's data analyst that a long-running job for a specific workflow + has now completed, allowing them to begin working with the latest output. + +Whenever a webhook is triggered, the act of Unstructured sending the notification data payload is called a +_notification_. You can get a count or a list of these notifications. You can also mark them in your Unstructured account as read after +you have processed them according to your organization's needs. Marking a notification as read can help you keep track of +which notifications you have already dealt with and which ones you still need to take action on. + +## Requirements + +To create, view, and manage webhooks, Unstructured provides a set of Representational State Transfer (REST) endpoints. You can +call these endpoints through standard REST-enabled utilities, tools, programming languages, packages, and libraries. +The examples, shown later on this page, describe how to call the Unstructured API's webhook operations with +`curl` and Postman. You can adapt this information as needed for your preferred programming languages and libraries, +for example by using the `requests` library with Python. + +To call the Unstructured API's webhook operations, you must have an Unstructured API URL and a valid Unstructured API key. + +To get your Unstructured API URL, do the following: + +import GetStartedAPIURLOnly from '/snippets/general-shared-text/get-started-api-url-only.mdx'; + + + +To get your Unstructured API key, do the following: + +import GetStartedSimpleAPIOnly from '/snippets/general-shared-text/get-started-simple-api-only.mdx'; + + + +In the following examples, the API URL and API key are represented by the following placeholders, respectively: + +- `UNSTRUCTURED_API_URL` +- `UNSTRUCTURED_API_KEY` + +To learn how to set these placeholders as variables, see the `curl` or Postman documentation. + +## Create an account-scoped notification channel + +To create a webhook that is trigged for all corresponding events across your Unstructured account, +call the `POST /notifications/channels` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with your receiver's webhook URL. +- Replace `` with the programmatic name of the event that you want to trigger the webhook. To allow this + webhook to be triggered in succession for multiple events, add multiple `` entries. For the list of + available event types, see this article's introductory section. +- Replace `` with some meaningful description of the webhook, for your own reference. + + + + ```bash + curl --request 'POST' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \ + --header 'accept: application/json' \ + --data \ + '{ + "channel_type": "webhook", + "url": "", + "event_types": [ + "", + "" + ], + "description": "" + }' + ``` + + + 1. In the method drop-down list, select **POST**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels + ``` + + 3. On the **Headers** tab, enter the following headers: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + - **Key**: `accept`, **Value**: `application/json` + + 4. On the **Body** tab, select **raw** and **JSON**, and specify the settings for the notification channel: + + ```json + { + "channel_type": "webhook", + "url": "", + "event_types": [ + "", + "" + ], + "description": "" + } + ``` + + 5. Click **Send**. + + + +## List account-scoped notification channels + +## Get an account-scoped notification channel + +## Update an account-scoped notification channel + +## Delete an account-scoped notification channel + +## Create a workflow-scoped notification channel + +## List workflow-scoped notification channels + +## Get a workflow-scoped notification channel + +## Update a workflow-scoped notification channel + +## Delete a workflow-scoped notification channel + +## List all notifications + +## Get a notification + +## Mark a notification as read + +## Get a count of unread notifications \ No newline at end of file diff --git a/docs.json b/docs.json index 97b9731e..3a7a2de2 100644 --- a/docs.json +++ b/docs.json @@ -144,7 +144,8 @@ "pages": [ "api-reference/overview", "api-reference/supported-file-types", - "api-reference/quickstart" + "api-reference/quickstart", + "api-reference/webhooks" ] }, { diff --git a/snippets/general-shared-text/get-started-api-url-only.mdx b/snippets/general-shared-text/get-started-api-url-only.mdx new file mode 100644 index 00000000..d5b0e528 --- /dev/null +++ b/snippets/general-shared-text/get-started-api-url-only.mdx @@ -0,0 +1,24 @@ +1. If you do not already have an Unstructured account, [sign up for free](https://unstructured.io/?modal=try-for-free). + After you sign up, you are automatically signed in to your new Unstructured **Let's Go** account, at [https://platform.unstructured.io](https://platform.unstructured.io). + + + To sign up for a **Business** account instead, [contact Unstructured Sales](https://unstructured.io/?modal=contact-sales), or [learn more](/api-reference/overview#pricing). + + +2. If you have an Unstructured **Let's Go**, **Pay-As-You-Go**, or **Business SaaS** account and are not already signed in, sign in to your account at [https://platform.unstructured.io](https://platform.unstructured.io). + + + For other types of **Business** accounts, see your Unstructured account administrator for sign-in instructions, + or email Unstructured Support at [support@unstructured.io](mailto:support@unstructured.io). + + +3. Get your Unstructured API URL:
+ + a. After you sign in to your Unstructured **Let's Go**, **Pay-As-You-Go**, or **Business** account, click **API Keys** on the sidebar.
+ + + For a **Business** account, before you click **API Keys**, make sure you have selected the organizational workspace you want to get the API URL for. + [Learn more](https://docs.unstructured.io/ui/account/workspaces#access-a-workspace). + + + b. Copy the value of **Unstructured API Endpoint** to your system's clipboard. \ No newline at end of file From 51588dfae2f6a3cd91fa9dd4f91525b95f685b1d Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Mon, 9 Feb 2026 14:08:40 -0800 Subject: [PATCH 3/4] Added missing API ref. Adding UI how-to. --- api-reference/webhooks.mdx | 637 +++++++++++++++++++++++++++++++++++-- docs.json | 3 +- ui/webhooks.mdx | 127 ++++++++ 3 files changed, 734 insertions(+), 33 deletions(-) create mode 100644 ui/webhooks.mdx diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx index a0cc64df..2740448d 100644 --- a/api-reference/webhooks.mdx +++ b/api-reference/webhooks.mdx @@ -2,9 +2,7 @@ title: Webhooks --- -A _webhook_ is a way for a _sender_ (also sometimes called a _source_, _provider_, _producer_, or _sender -application_) to send data to a _receiver_ (also sometimes called a _destination_, _consumer_, -_receiver application_, or simply an _endpoint_). For Unstructured webhooks, Unstructured is the sender, +A _webhook_ is a common technique that allows a _sender_ to automatically send data to a _receiver_ based on events that happen in the sender. For Unstructured webhooks, Unstructured is the sender, and your solution is the receiver. Some popular receivers include [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/urls-webhook-tutorial.html), [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-bindings-http-webhook), @@ -14,37 +12,55 @@ and your solution is the receiver. Some popular receivers include [Svix](https://svix.com), and [Webhook.site](https://webhook.site/). -The receiver provides a unique URL (often called the -_webhook URL_, _callback URL_, or _notification URL_), to receive the data from Unstructured. -Unstructured calls the webhook URL by using an HTTP POST operation and -passes a payload of data to the receiver in JSON format. The receiver then processes the payload and can decide +The receiver provides a unique URL, called the +_webhook URL_, to receive the data that Unstructured sends. +Behind the scenes, when specific events happen in Unstructured, Unstructured then automatically calls the webhook URL by using an HTTP POST operation and +passes payloads of data in JSON format related to those events to the receiver. The receiver then processes the payload and can decide what to do with the data from there. -Because webhooks are event-driven, something must first happen to trigger the webhook. In +Because webhooks are event-driven, some event must first be triggered to begin generating the related data to be sent. In Unstructured, these webhooks can be triggered whenever a [job](/api-reference/workflow/jobs) that is associated with its target [workflow](/api-reference/workflow/workflows) does one or more of the following: -- Is scheduled (programmatically, an event type of `job.scheduled`) -- Begins its work (`job.in_progress`) -- Has stopped (`job.stopped`) -- Fails (`job.failed`) -- Is completed (`job.completed`) +- Is scheduled to start running later (programmatically, an event type of `job.scheduled`) +- Has begun running (`job.in_progress`) +- Has stopped running (`job.stopped`) +- Has failed to successfully complete (`job.failed`) +- Has successfully completed (`job.completed`) When a webhook is configured to deliver event-driven notification data payloads from a sender to a receiver, this configuration is called a _notification channel_. For Unstructured webhooks, notification channels can be created and managed at the following levels: -- At the account level, known as an _account-scoped notification channel_. This allows any job that is associated with any - workflow in the account to trigger the webhook. This can be useful for example for routing pager requests to a team of on-call engineers in an - IT operations center whenever any job fails across the organization. -- At the workflow level, known as _workflow-scoped notification channels_. This allows any job that is associated only with - the target workflow to trigger the webhook. This can be useful for example for emailing a department's data analyst that a long-running job for a specific workflow +- At the **workspace** level, known as a _workspace-scoped notification channel_. This allows any job that is associated with a + workspace in an Unstructured account to trigger the webhook. This can be useful for example for routing pager requests to a team of on-call engineers in an + IT operations center whenever any job fails across the workspace. + + + Each **Let's Go** or **Pay-As-You-Go** account has one and only one workspace. + + An Unstructured **Business** account can have multiple workspaces. + + +- At the **workflow** level, known as a _workflow-scoped notification channel_. This allows any job that is associated only with + the target workflow in an Unstructured account to trigger the webhook. This can be useful for example for emailing a department's data analyst that a long-running job for a specific workflow has now completed, allowing them to begin working with the latest output. -Whenever a webhook is triggered, the act of Unstructured sending the notification data payload is called a +Whenever a webhook is triggered, the act of Unstructured sending the event data payload is called a _notification_. You can get a count or a list of these notifications. You can also mark them in your Unstructured account as read after you have processed them according to your organization's needs. Marking a notification as read can help you keep track of which notifications you have already dealt with and which ones you still need to take action on. +This article describes how to create, view, and manage webhooks and notifications at both the workspace and workflow levels by using the Unstructured API. + + + The Unstructured user interface (UI) allows limited creation, viewing, and managing of webhooks only, as follows ([learn how](/ui/webhooks)): + + - Webhooks for a personal Unstructured workspace. Each personal Unstructured account has one and only one personal Unstructured workspace. + - Webhooks for a workspace within an Unstructured **Business** account. + + You cannot use the Unstructured UI to create, view, or manage notifications or workflow-level webhooks. + + ## Requirements To create, view, and manage webhooks, Unstructured provides a set of Representational State Transfer (REST) endpoints. You can @@ -72,20 +88,25 @@ In the following examples, the API URL and API key are represented by the follow - `UNSTRUCTURED_API_URL` - `UNSTRUCTURED_API_KEY` + + Each Unstructured API key works with one and only one workspace (and the workflows within that workspace). Make sure you are using the right API key + for your target workspace! + + To learn how to set these placeholders as variables, see the `curl` or Postman documentation. -## Create an account-scoped notification channel +## Create a workspace-scoped notification channel -To create a webhook that is trigged for all corresponding events across your Unstructured account, +To create a notification channel that is used for all corresponding events across a workspace, call the `POST /notifications/channels` operation. In the following examples, replace the following placeholders: - Replace `` with your receiver's webhook URL. -- Replace `` with the programmatic name of the event that you want to trigger the webhook. To allow this - webhook to be triggered in succession for multiple events, add multiple `` entries. For the list of +- Replace `` with the programmatic name of the event that you want to trigger. To allow multiple + events to be triggered, add multiple `` entries. For the list of available event types, see this article's introductory section. -- Replace `` with some meaningful description of the webhook, for your own reference. +- Replace `` with some meaningful description of the notification channel, for your own reference. @@ -137,28 +158,580 @@ In the following examples, replace the following placeholders: -## List account-scoped notification channels +## List all workspace-scoped notification channels + +To get a list of all notification channels that are used for all corresponding events across a workspace, +call the `GET /notifications/channels` operation. + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels?channel_type=webhook" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels + ``` + + 3. On the **Params** tab, enter the following query parameter: + + - **Key**: `channel_type`, **Value**: `webhook` + + 4. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 5. Click **Send**. + + + +## Get a workspace-scoped notification channel + +To get information about a notification channel that is used for all corresponding events across a workspace, +call the `GET /notifications/channels/` operation. + +In the following examples, replace `` with the workspace-scoped notification channel's unique ID. +To get this ID, see [List all workspace-scoped notification channels](#list-all-workspace-scoped-notification-channels). + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + + +## Update a workspace-scoped notification channel + +To change the settings of a notification channel that is used for all corresponding events across a workspace, +call the `PATCH /notifications/channels/` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with the workspace-scoped notification channel's unique ID. + To get this ID, see [List all workspace-scoped notification channels](#list-all-workspace-scoped-notification-channels). +- Replace any or all of the following settings with the new settings you want to use for the notification channel: + + - ``: Your receiver's webhook URL. + - ``: The programmatic name of the event that you want to trigger. To allow multiple + events to be triggered, add multiple `` entries. For the list of + available event types, see this article's introductory section. + - ``: Some meaningful description of the notification channel, for your own reference. + - For `enabled`: Set to true to enable the notification channel, or false to disable it. + + + + ```bash + curl --request 'PATCH' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \ + --header 'content-type: application/json' \ + --data \ + '{ + "url": "", + "event_types": [ + "", + "" + ], + "description": "", + "enabled": "" + }' + ``` + + + 1. In the method drop-down list, select **PATCH**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. On the **Body** tab, select **raw** and **JSON**, and specify any settings to change for the notification channel: + + ```json + { + "url": "", + "event_types": [ + "", + "" + ], + "description": "", + "enabled": "" + } + ``` + + 5. Click **Send**. + + + +## Delete a workspace-scoped notification channel -## Get an account-scoped notification channel + + Deleting a workspace-scoped notification channel is a permanent action and is not recoverable. + -## Update an account-scoped notification channel +To delete a notification channel that is used for all corresponding events across a workspace, +call the `DELETE /notifications/channels/` operation. -## Delete an account-scoped notification channel +In the following examples, replace `` with the workspace-scoped notification channel's unique ID. +To get this ID, see [List all workspace-scoped notification channels](#list-all-workspace-scoped-notification-channels). + + + + ```bash + curl --request 'DELETE' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **DELETE**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + ## Create a workflow-scoped notification channel -## List workflow-scoped notification channels +To create a notification channel that is used only for a specific workflow, +call the `POST /workflows//notifications/channels` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with the workflow's unique ID. + To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). +- Replace `` with your receiver's webhook URL. +- Replace `` with the programmatic name of the event that you want to trigger. To allow multiple + events to be triggered, add multiple `` entries. For the list of + available event types, see this article's introductory section. +- Replace `` with some meaningful description of the notification channel, for your own reference. + + + + ```bash + curl --request 'POST' --location \ + "$UNSTRUCTURED_API_URL/workflows//notifications/channels" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \ + --header 'accept: application/json' \ + --data \ + '{ + "channel_type": "webhook", + "url": "", + "event_types": [ + "", + "" + ], + "description": "" + }' + ``` + + + 1. In the method drop-down list, select **POST**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/workflows//notifications/channels + ``` + + 3. On the **Headers** tab, enter the following headers: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + - **Key**: `accept`, **Value**: `application/json` + + 4. On the **Body** tab, select **raw** and **JSON**, and specify the settings for the notification channel: + + ```json + { + "channel_type": "webhook", + "url": "", + "event_types": [ + "", + "" + ], + "description": "" + } + ``` + + 5. Click **Send**. + + + +## List all workflow-scoped notification channels + +To get a list of all notification channels that are used only for a specific workflow, +call the `GET /workflows//notifications/channels` operation. + +In the following examples, replace `` with the workflow's unique ID. +To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/workflows//notifications/channels?channel_type=webhook" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/workflows//notifications/channels + ``` + + 3. On the **Params** tab, enter the following query parameter: + + - **Key**: `channel_type`, **Value**: `webhook` + + 4. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 5. Click **Send**. + + ## Get a workflow-scoped notification channel +To get information about a notification channel that is used only for a specific workflow, +call the `GET /workflows//notifications/channels/` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with the workflow's unique ID. + To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). +- Replace`` with the workspace-scoped notification channel's unique ID. + To get this ID, see [List all workflow-scoped notification channels](#list-all-workflow-scoped-notification-channels). + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/workflows//notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/workflows//notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + + ## Update a workflow-scoped notification channel +To change the settings of a notification channel that is used only for a specific workflow, +call the `PATCH /workflows//notifications/channels/` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with the workflow's unique ID. + To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). +- Replace`` with the workspace-scoped notification channel's unique ID. + To get this ID, see [List all workflow-scoped notification channels](#list-all-workflow-scoped-notification-channels). +- Replace any or all of the following settings with the new settings you want to use for the notification channel: + + - ``: Your receiver's webhook URL. + - ``: The programmatic name of the event that you want to trigger. To allow multiple + events to be triggered, add multiple `` entries. For the list of + available event types, see this article's introductory section. + - ``: Some meaningful description of the notification channel, for your own reference. + - For `enabled`: Set to true to enable the notification channel, or false to disable it. + + + + ```bash + curl --request 'PATCH' --location \ + "$UNSTRUCTURED_API_URL/workflows//notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \ + --header 'content-type: application/json' \ + --data \ + '{ + "url": "", + "event_types": [ + "", + "" + ], + "description": "", + "enabled": "" + }' + ``` + + + 1. In the method drop-down list, select **PATCH**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/workflows//notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. On the **Body** tab, select **raw** and **JSON**, and specify any settings to update for the notification channel: + + ```json + { + "url": "", + "event_types": [ + "", + "" + ], + "description": "", + "enabled": "" + } + ``` + + 5. Click **Send**. + + + ## Delete a workflow-scoped notification channel -## List all notifications + + Deleting a workflow-scoped notification channel is a permanent action and is not recoverable. + + +To delete a notification channel that is used only for a specific workflow, +call the `DELETE /workflows//notifications/channels/` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with the workflow's unique ID. + To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). +- Replace`` with the workflow-scoped notification channel's unique ID. + To get this ID, see [List all workflow-scoped notification channels](#list-all-workflow-scoped-notification-channels). + + + + ```bash + curl --request 'DELETE' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **DELETE**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + + +## List all notifications for a workspace + +To list all notifications for a workspace, call the `GET /notifications` operation. + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/notifications" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + ## Get a notification -## Mark a notification as read +To get information about a notification for a workspace, +call the `GET /notifications/` operation. + +In the following examples, replace `` with the notification's unique ID. +To get this ID, see [List all notifications for a workspace](#list-all-notifications-for-a-workspace). + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/notifications/" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/ + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + + +## Mark notifications as read + +To mark any number of notifications as read, +call the `GET /notifications/mark-read` operation. + +In the following examples, replace the following placeholders: + +- Replace `` with your receiver's webhook URL. +- Replace `` with the unique ID of the notification that you want to mark as read. To allow multiple + notifications to be marked as read, add multiple `` entries. To get these IDs, see [List all notifications for a workspace](#list-all-notifications-for-a-workspace). +- Replace `` to mark all notifications sent before the specified timestamp as read. The value must be a valid ISO 8601 timestamp in the + format `YYYY-MM-DDTHH:MM:SSZ`, for example `2024-09-19T15:45:30Z`. +- For `mark_all`, set to `true` to mark all notifications as read. +- Replace `` with the unique ID of the workflow that the notification is associated with. + To get this ID, see [List workflows](/api-reference/workflow/overview#list-workflows). +- Only one of the following can be specified: `notification_ids`, `before`, or `mark_all`. +- If you specify `workflow_id`, you must also specify `before` or `mark_all`. + +This results in the following behaviors: + +- If you specify `notification_ids` only, it will mark all notifications with the specified IDs as read. +- If you specify `before` only, it will mark all notifications created in the workspace before the specified timestamp as read. +- If you specify `mark_all` only, it will mark at the time of the API call all existing notifications in the workspace as read. +- If you specify `workflow_id` and `before`, it will mark all notifications created before the specified timestamp for the specified workflow as read. +- If you specify `workflow_id` and `mark_all`, it will mark at the time of the API call all existing notifications associated with the specified workflow as read. -## Get a count of unread notifications \ No newline at end of file + + + ```bash + curl --request 'POST' --location \ + "$UNSTRUCTURED_API_URL/notifications/mark-read" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \ + --header 'accept: application/json' \ + --data \ + '{ + "notification_ids": [ + "", + "" + ], + "before": "", + "mark_all": "true", + "workflow_id": "" + }' + ``` + + + 1. In the method drop-down list, select **POST**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/mark-read + ``` + + 3. On the **Headers** tab, enter the following headers: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + - **Key**: `accept`, **Value**: `application/json` + + 4. On the **Body** tab, select **raw** and **JSON**, and specify the settings for the notification channel: + + ```json + { + "notification_ids": [ + "", + "" + ], + "before": "", + "mark_all": "true", + "workflow_id": "" + } + ``` + + 5. Click **Send**. + + + +## Get a count of all unread notifications for a workspace + +To get a count of all unread notifications for a workspace, call the `GET /notifications/count` operation. + + + + ```bash + curl --request 'GET' --location \ + "$UNSTRUCTURED_API_URL/notifications/count" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **GET**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/count + ``` + + 3. On the **Headers** tab, enter the following header: + + - **Key**: `unstructured-api-key`, **Value**: `{{UNSTRUCTURED_API_KEY}}` + + 4. Click **Send**. + + \ No newline at end of file diff --git a/docs.json b/docs.json index 3a7a2de2..e64fe172 100644 --- a/docs.json +++ b/docs.json @@ -110,7 +110,8 @@ "ui/account/workspaces", "ui/account/roles" ] - } + }, + "ui/webhooks" ] }, { diff --git a/ui/webhooks.mdx b/ui/webhooks.mdx new file mode 100644 index 00000000..427b8130 --- /dev/null +++ b/ui/webhooks.mdx @@ -0,0 +1,127 @@ +--- +title: Webhooks +--- + +A _webhook_ is a common technique that allows a _sender_ to automatically send data to a _receiver_ based on events that happen in the sender. For Unstructured webhooks, Unstructured is the sender, +and your solution is the receiver. Some popular receivers include +[AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/urls-webhook-tutorial.html), +[Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-bindings-http-webhook), +[Google Cloud Run](https://docs.cloud.google.com/run/docs/triggering/webhooks), +[Zapier](https://zapier.com/blog/what-are-webhooks/), +[Slack](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/), +[Svix](https://svix.com), and +[Webhook.site](https://webhook.site/). + +Your solution provides a unique URL, called the +_webhook URL_, to receive the data that Unstructured sends. +Behind the scenes, when specific events happen in Unstructured, Unstructured then automatically calls the webhook URL and +passes to this webhook URL payloads of data in JSON format related to those events. The receiver then processes these payloads and can decide +what to do with the data from there. + +Because webhooks are event-driven, some event must first be triggered to begin generating the related data to be sent. In +Unstructured, these webhooks can be triggered whenever a [job](/ui/jobs) that is associated with its target [workflow](/ui/workflows) does +one or more of the following: + +- Is scheduled to start running later (in the user interface, **Job scheduled**) +- Has begun running (**Job in progress**) +- Has stopped running (**Job stopped**) +- Has failed to successfully complete (**Job failed**) +- Has successfully completed (**Job completed**) + +Unstructured webhooks can be created and managed at the following levels: + +- At the **workspace** level. This allows any job that is associated with any + workspace in an Unstructured account to trigger the webhook. This can be useful for example for routing pager requests to a team of on-call engineers in an + IT operations center whenever any job fails across the workspace. + + + Each **Let's Go** or **Pay-As-You-Go** account has one and only one workspace. + + An Unstructured **Business** account can have multiple workspaces. + + Workspace-level webhooks can be created, viewed, and managed with the + Unstructured user interface (UI) ([learn how](#create-a-workspace-level-webhook)) or with the + Unstructured API ([learn how](/api-reference/webhooks)). + + +- At the **workflow** level. This allows any job that is associated only with + the target workflow to trigger the webhook. This can be useful for example for emailing a department's data analyst that a long-running job for a specific workflow + has now completed, allowing them to begin working with the latest output. + + + Workflow-level webhooks can be created, viewed, and managed only with the + Unstructured API. [Learn how](/api-reference/webhooks). + + +Whenever a webhook is triggered, the act of Unstructured sending the event data payload to a receiver is called a +_notification_. You can get a count or a list of these notifications. You can also mark them in your Unstructured account as read after +you have processed them according to your organization's needs. Marking a notification as read can help you keep track of +which notifications you have already dealt with and which ones you still need to take action on. + + + Notifications can be created, viewed, and managed only with the Unstructured API. [Learn how](/api-reference/webhooks). + + +## Create a workspace-level webhook + +To create a webhook that sends notifications for all specified events that happen across a workspace, regardless of the +resource that triggers the event, do the following: + +1. If you are not already signed in, sign in to your Unstructured account. +2. Open your target workspace as follows: + + - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. + Skip ahead to Step 3. + - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now + ([learn how](/ui/account/workspaces#access-a-workspace)). + +3. Click the **Webhooks** tab. +4. Click **Add Webhook +**. +5. In the **Webhook Setup** dialog, for **Webhook URL**, enter the target receiver's webhook URL. +6. Optionally, for **Description**, enter a meaningful description of the webhook, for your own reference. +7. For **Select Events**, click one or more of the available events that you want to Unstructured to send a notification for. + For more information about the list of available events, see this article's introductory section. +8. Click **Save Webhook**. + +The new webhook is created and appears in the list of available webhooks. + +## Change a workspace-level webhook's settings + +To change the settings for an existing webhook that sends notifications for all specified events that happen across a workspace, do the following: + +1. If you are not already signed in, sign in to your Unstructured account. +2. Open your target workspace as follows: + + - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. + Skip ahead to Step 3. + - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now + ([learn how](/ui/account/workspaces#access-a-workspace)). + +3. Click the **Webhooks** tab. +4. In the list of available webhooks, click the name of the webhook you want to change the settings for. +5. In the webhook's settings pane, make the desired changes. +6. When you are done making your changes, click **Save Changes**. + +The webhook's settings are updated, and the new settings begin taking effect. + +## Delete a workspace-level webhook + + + Deleting a webhook is a permanent action and is not recoverable. + + +To delete an existing webhook that sends notifications for all specified events that happen across a workspace, do the following: + +1. If you are not already signed in, sign in to your Unstructured account. +2. Open your target workspace as follows: + + - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. + Skip ahead to Step 3. + - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now + ([learn how](/ui/account/workspaces#access-a-workspace)). + +3. Click the **Webhooks** tab. +4. In the list of available webhooks, click the name of the webhook you want to delete. +5. In the webhook's settings pane, click **Delete Webhook**. + +The webhook is deleted, and notifications will no longer be sent for this webhook. \ No newline at end of file From 8a61d0ecad20a566d7f42843840eba9cc16cca9b Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Tue, 10 Feb 2026 06:47:11 -0800 Subject: [PATCH 4/4] Generalized webhook UI instructions --- ui/webhooks.mdx | 124 +++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 65 deletions(-) diff --git a/ui/webhooks.mdx b/ui/webhooks.mdx index 427b8130..a18b2d6b 100644 --- a/ui/webhooks.mdx +++ b/ui/webhooks.mdx @@ -28,100 +28,94 @@ one or more of the following: - Has failed to successfully complete (**Job failed**) - Has successfully completed (**Job completed**) -Unstructured webhooks can be created and managed at the following levels: +Unstructured webhooks can be created and managed for the following scopes: + +- In your Unstructured personal account, or for a workspace within an Unstructured **Business** account. + This allows any job that is associated with any workflow across this scope to trigger the webhook. This can be useful + for example for routing pager requests to a team of on-call engineers in an IT operations center + whenever any job fails within this scope. +- For an individual workflow. This allows any job that is associated only with + the target workflow to trigger the webhook. This can be useful for example for emailing a department's data analyst + that a long-running job for a specific workflow + has now completed, allowing them to begin working with the latest output. + +Webhooks within the personal account and workspace scope can be created, viewed, and managed with the +Unstructured user interface (UI), as described later in this article. They can also be created, viewed, and +managed with the +Unstructured API ([learn how](/api-reference/webhooks)). -- At the **workspace** level. This allows any job that is associated with any - workspace in an Unstructured account to trigger the webhook. This can be useful for example for routing pager requests to a team of on-call engineers in an - IT operations center whenever any job fails across the workspace. +Whenever a webhook is triggered, the act of Unstructured sending the event data payload to a receiver is called a +_notification_. You can get a count or a list of these notifications. You can also mark them as read after +you have processed them according to your organization's needs. Marking a notification as read can help you keep track of +which notifications you have already dealt with and which ones you still need to take action on. - - Each **Let's Go** or **Pay-As-You-Go** account has one and only one workspace. +Notifications can be created, viewed, and managed only with the Unstructured API. [Learn how](/api-reference/webhooks). - An Unstructured **Business** account can have multiple workspaces. +## View your personal account webhooks - Workspace-level webhooks can be created, viewed, and managed with the - Unstructured user interface (UI) ([learn how](#create-a-workspace-level-webhook)) or with the - Unstructured API ([learn how](/api-reference/webhooks)). - +To view the webhooks for your Unstructured personal account, do the following: -- At the **workflow** level. This allows any job that is associated only with - the target workflow to trigger the webhook. This can be useful for example for emailing a department's data analyst that a long-running job for a specific workflow - has now completed, allowing them to begin working with the latest output. +1. If you are not already signed in, sign in to your Unstructured account. +2. If you have an Unstructured **Business** account, in the top navigation bar's account selector, select **Personal Account**. +3. In the sidebar, click your user icon, and then click **Account Settings**. +4. In the top navigation bar, click the **Webhooks** tab. - - Workflow-level webhooks can be created, viewed, and managed only with the - Unstructured API. [Learn how](/api-reference/webhooks). - +The webhooks for your personal account are displayed. -Whenever a webhook is triggered, the act of Unstructured sending the event data payload to a receiver is called a -_notification_. You can get a count or a list of these notifications. You can also mark them in your Unstructured account as read after -you have processed them according to your organization's needs. Marking a notification as read can help you keep track of -which notifications you have already dealt with and which ones you still need to take action on. +## View workspace webhooks + +To view the webhooks for a workspace within an Unstructured **Business** account, do the following: + +1. If you are not already signed in, sign in to your Unstructured account. +2. In the top navigation bar, in the account selector, select the account for your target workspace. +3. Next to the account selector, in the workspace selector, select your target workspace. +4. In the sidebar, click the **Settings** (gear) icon, and then click **Manage Workspace**. +5. Below the top navigation bar, click the **Webhooks** tab. - - Notifications can be created, viewed, and managed only with the Unstructured API. [Learn how](/api-reference/webhooks). - +The webhooks for this workspace are displayed. -## Create a workspace-level webhook +## Create a webhook -To create a webhook that sends notifications for all specified events that happen across a workspace, regardless of the +To create a webhook that sends notifications for all specified events within the selected scope, regardless of the resource that triggers the event, do the following: 1. If you are not already signed in, sign in to your Unstructured account. -2. Open your target workspace as follows: - - - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. - Skip ahead to Step 3. - - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now - ([learn how](/ui/account/workspaces#access-a-workspace)). - -3. Click the **Webhooks** tab. -4. Click **Add Webhook +**. -5. In the **Webhook Setup** dialog, for **Webhook URL**, enter the target receiver's webhook URL. -6. Optionally, for **Description**, enter a meaningful description of the webhook, for your own reference. -7. For **Select Events**, click one or more of the available events that you want to Unstructured to send a notification for. +2. [View your personal account webhooks](#view-your-personal-account-webhooks) or + [view workspace webhooks](#view-workspace-webhooks), depending on the scope of the webhook you want to create. +3. Click **Add Webhook +**. +4. In the **Webhook Setup** dialog, for **Webhook URL**, enter the target receiver's webhook URL. +5. Optionally, for **Description**, enter a meaningful description of the webhook, for your own reference. +6. For **Select Events**, click one or more of the available events that you want to Unstructured to send a notification for. For more information about the list of available events, see this article's introductory section. -8. Click **Save Webhook**. +7. Click **Save Webhook**. The new webhook is created and appears in the list of available webhooks. -## Change a workspace-level webhook's settings +## Change a webhook's settings -To change the settings for an existing webhook that sends notifications for all specified events that happen across a workspace, do the following: +To change the settings for an existing webhook, do the following: 1. If you are not already signed in, sign in to your Unstructured account. -2. Open your target workspace as follows: - - - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. - Skip ahead to Step 3. - - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now - ([learn how](/ui/account/workspaces#access-a-workspace)). - -3. Click the **Webhooks** tab. -4. In the list of available webhooks, click the name of the webhook you want to change the settings for. -5. In the webhook's settings pane, make the desired changes. -6. When you are done making your changes, click **Save Changes**. +2. [View your personal account webhooks](#view-your-personal-account-webhooks) or + [view workspace webhooks](#view-workspace-webhooks), depending on where the target webhook is located. +3. In the list of available webhooks, click the name of the webhook you want to change the settings for. +4. In the webhook's settings pane, make the desired changes. +5. When you are done making your changes, click **Save Changes**. The webhook's settings are updated, and the new settings begin taking effect. -## Delete a workspace-level webhook +## Delete a webhook Deleting a webhook is a permanent action and is not recoverable. -To delete an existing webhook that sends notifications for all specified events that happen across a workspace, do the following: +To delete an existing webhook, do the following: 1. If you are not already signed in, sign in to your Unstructured account. -2. Open your target workspace as follows: - - - If you have an Unstructured **Let's Go** or **Pay-As-You-Go** account, your one and only workspace is already opened by default. - Skip ahead to Step 3. - - If you have an Unstructured **Business** account, and you have not already opened the target workspace, select it now - ([learn how](/ui/account/workspaces#access-a-workspace)). - -3. Click the **Webhooks** tab. -4. In the list of available webhooks, click the name of the webhook you want to delete. -5. In the webhook's settings pane, click **Delete Webhook**. +2. [View your personal account webhooks](#view-your-personal-account-webhooks) or + [view workspace webhooks](#view-workspace-webhooks), depending on where the target webhook is located. +3. In the list of available webhooks, click the name of the webhook you want to delete. +4. In the webhook's settings pane, click **Delete Webhook**. The webhook is deleted, and notifications will no longer be sent for this webhook. \ No newline at end of file