diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx new file mode 100644 index 00000000..2740448d --- /dev/null +++ b/api-reference/webhooks.mdx @@ -0,0 +1,737 @@ +--- +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/). + +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, 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 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 **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 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 +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` + + + 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 a workspace-scoped notification channel + +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. 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/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 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 + + + Deleting a workspace-scoped notification channel is a permanent action and is not recoverable. + + +To delete a notification channel that is used for all corresponding events across a workspace, +call the `DELETE /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 '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 + +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 + + + 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 + +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. + + + + ```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 97b9731e..e64fe172 100644 --- a/docs.json +++ b/docs.json @@ -110,7 +110,8 @@ "ui/account/workspaces", "ui/account/roles" ] - } + }, + "ui/webhooks" ] }, { @@ -144,7 +145,8 @@ "pages": [ "api-reference/overview", "api-reference/supported-file-types", - "api-reference/quickstart" + "api-reference/quickstart", + "api-reference/webhooks" ] }, { 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 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 diff --git a/ui/webhooks.mdx b/ui/webhooks.mdx new file mode 100644 index 00000000..a18b2d6b --- /dev/null +++ b/ui/webhooks.mdx @@ -0,0 +1,121 @@ +--- +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 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)). + +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. + +Notifications can be created, viewed, and managed only with the Unstructured API. [Learn how](/api-reference/webhooks). + +## View your personal account webhooks + +To view the webhooks for your Unstructured personal account, do the following: + +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. + +The webhooks for your personal account are displayed. + +## 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. + +The webhooks for this workspace are displayed. + +## Create a webhook + +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. [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. +7. Click **Save Webhook**. + +The new webhook is created and appears in the list of available webhooks. + +## Change a webhook's settings + +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. [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 webhook + + + Deleting a webhook is a permanent action and is not recoverable. + + +To delete an existing webhook, do the following: + +1. If you are not already signed in, sign in to your Unstructured account. +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