diff --git a/api-reference/webhooks.mdx b/api-reference/webhooks.mdx new file mode 100644 index 00000000..9d6d3883 --- /dev/null +++ b/api-reference/webhooks.mdx @@ -0,0 +1,866 @@ +--- +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. +Some common uses for webhooks include sending real-time notifications such as emails, pages, or alerts to messaging apps; automatically +triggering build, test, or deployment workflows in CI/CD pipelines; launching downstream data synchronization updates; or triggering agentic AI workflows. + +For Unstructured webhooks, Unstructured is the sender, +and your solution is the receiver. Some popular receiver solutions 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 automatically calls the webhook URL by using an HTTP POST operation and +passes JSON payloads related to those events to the receiver. The receiver then processes the payload and decides what to do with the data. + +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`) - less than 90% of the job's files or data were successfully processed. +- Has successfully completed (`job.completed`) - 90% or more of the job's files or data were successfully processed. + +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 a 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 when a long-running job for a specific workflow + has completed, allowing them to begin working with the latest output. + +Whenever a notification channel is created, a secret is generated for it. You can have Unstructured generate the secret value, or you can specify the value yourself. Use this secret in your receiver application to verify incoming webhook requests. The secret is write-only and is not returned by the API after creation. If you suspect that the secret has been compromised, rotate it to a new value. + +The following Python example shows how to verify an incoming webhook request by using the notification channel secret, request headers, and raw request body. + + +```python +import hashlib +import hmac +import base64 +import time + + +def verify_webhook( + payload: bytes, headers: dict, secret: str, tolerance_seconds: int = 300 +) -> bool: + msg_id = headers["webhook-id"] + timestamp = headers["webhook-timestamp"] + signature_header = headers["webhook-signature"] + + # Reject stale timestamps + if abs(time.time() - int(timestamp)) > tolerance_seconds: + raise ValueError("Timestamp too old") + + # Use the secret as the signing key + secret_bytes = secret.encode("utf-8") + + # Sign: "{msg_id}.{timestamp}.{raw_body}" + signed_content = f"{msg_id}.{timestamp}.".encode() + payload + expected = base64.b64encode( + hmac.new(secret_bytes, signed_content, hashlib.sha256).digest() + ).decode() + + # The header may contain multiple space-separated versioned sigs + for sig in signature_header.split(" "): + version, value = sig.split(",", 1) + if version == "v1" and hmac.compare_digest(expected, value): + return True + + raise ValueError("Invalid signature") + ``` + + +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. + + + The Unstructured user interface (UI) allows only limited creation, viewing, and management of webhooks, 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. +- Optionally, replace `` with the signing secret in plain text for the notification channel. If you do not provide a secret, Unstructured generates a random secret for you. The secret must be between 24 and 75 bytes (24 to 75 ASCII characters). + + + The secret is write-only and is not returned by the API after creation. If you need to change it later, update it or [rotate this workspace-scoped notification channel's secret](#rotate-the-secret-for-a-workspace-scoped-notification-channel). + + + + + ```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": "", + "secret": "" + }' + ``` + + + 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**. + + + +## Rotate the secret for a workspace-scoped notification channel + +To _rotate_ (generate a new, replacement) secret for a notification channel that is used for all corresponding events across a workspace, +call the `POST /notifications/channels//secret/rotate` 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 'POST' --location \ + "$UNSTRUCTURED_API_URL/notifications/channels//secret/rotate" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 1. In the method drop-down list, select **POST**. + 2. In the address box, enter the following URL: + + ```text + {{UNSTRUCTURED_API_URL}}/notifications/channels//secret/rotate + ``` + + 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. + - ``: A new signing secret in plain text for the notification channel. Omit `secret` to keep the current value. The secret must be between 24 and 75 bytes (24 to 75 ASCII characters). + - 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": "", + "secret": "", + "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": "", + "secret": "", + "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. +- Optionally, replace `` with the signing secret in plain text for the notification channel. If you do not provide a secret, Unstructured generates a random secret for you. The secret must be between 24 and 75 bytes (24 to 75 ASCII characters). + + + The secret is write-only and is not returned by the API after creation. If you need to change it later, update it or [rotate this workflow-scoped notification channel's secret](#rotate-the-secret-for-a-workflow-scoped-notification-channel). + + + + + ```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": "", + "secret": "" + }' + ``` + + + 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**. + + + +## Rotate the secret for a workflow-scoped notification channel + +To _rotate_ (generate a new, replacement) secret for a notification channel that is used only for a specific workflow, +call the `POST /workflows//notifications/channels//secret/rotate` 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 'POST' --location \ + "$UNSTRUCTURED_API_URL/workflows//notifications/channels//secret/rotate" \ + --header "unstructured-api-key: $UNSTRUCTURED_API_KEY" + ``` + + + 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//secret/rotate + ``` + + 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. + - ``: A new signing secret in plain text for the notification channel. Omit `secret` to keep the current value. The secret must be between 24 and 75 bytes (24 to 75 ASCII characters). + - 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": "", + "secret": "", + "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": "", + "secret": "", + "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 marking notifications as read: + + ```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 6f8763a9..478d5b33 100644 --- a/docs.json +++ b/docs.json @@ -112,7 +112,8 @@ "ui/account/workspaces", "ui/account/roles" ] - } + }, + "ui/webhooks" ] }, { @@ -147,7 +148,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..0003dd01 --- /dev/null +++ b/ui/webhooks.mdx @@ -0,0 +1,128 @@ +--- +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. +Some common uses for webhooks include sending real-time notifications such as emails, pages, or alerts to messaging apps; automatically +triggering build, test, or deployment workflows in CI/CD pipelines; launching downstream data synchronization updates; or triggering agentic AI workflows. + +For Unstructured webhooks, Unstructured is the sender, +and your solution is the receiver. Some popular receiver solutions 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 automatically calls the webhook URL and +sends JSON payloads related to those events. The receiver then processes the payloads and decides what to do with the data. + +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**) - less than 90% of the job's files or data were successfully processed. +- Has successfully completed (**Job completed**) - 90% or more of the job's files or data were successfully processed. + +You can use the Unstructured user interface (UI) to create and manage webhooks in your Unstructured personal account, or for a +[workspace](/ui/account/workspaces) 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 the given scope. + +When you create a webhook in the UI, you can optionally provide a signing secret. If you do not provide one, Unstructured generates a random secret for you. You can later change the secret in the webhook settings pane, but you cannot view the existing secret value. + +## 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. Optionally, for **Secret**, enter a signing secret. If you do not provide one, Unstructured generates a random secret for you. +7. For **Select Events**, click one or more of the available events that you want Unstructured to send notifications 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 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 event data will no longer be sent through this webhook. + +## Unstructured API support for webhooks + +The Unstructured user interface (UI) only supports the creation and management of webhooks in your Unstructured personal account, or for a +workspace within an Unstructured **Business** account. + +You can also use the [Unstructured API](/api-reference/overview) to do this, as well as: + +- Create and manage webhooks at the workflow level, known as a _workflow-scoped notification channel_. 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 when a long-running job for a specific workflow + has completed, allowing them to begin working with the latest output. +- Create and rotate the secret for a webhook. You can optionally provide a secret when you create a webhook. If you do not provide one, Unstructured generates a random secret for you. You can also change the secret by using the Unstructured API. Use the secret to verify that a webhook originated from Unstructured. If you suspect that the secret has been compromised, rotate it to a new value. +- Manage notifications. 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 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. + +[Learn more](/api-reference/webhooks). +