Skip to main content
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, Azure Functions, Google Cloud Run, Zapier, Slack, Svix, and 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 that is associated with its target workflow 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 initialize (job.failed) - the job did not process any files.
  • Has completed (job.completed) - the job initialized and finished processing. To determine whether all files were processed successfully, get the job’s processing details. For more information, see Get processing details for a job.
You can use the Unstructured user interface (UI) to create and manage webhooks 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 the given scope. When you create a webhook in the UI, you can optionally provide a signing secret to verify incoming webhook requests. If you do not provide a secret, you cannot use secret-based verification for incoming webhook requests. The secret is write-only and is not returned by the API after creation.

​
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 or 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 strong, random signing secret in plain text. Use this secret to verify incoming webhook requests. If you do not provide a secret, you cannot use secret-based verification for incoming webhook requests. The secret must be between 24 and 75 bytes (24 to 75 ASCII characters).
  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 or 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 or 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 UI and API support for webhooks: workspace and workflow

The Unstructured user interface (UI) supports creating and managing webhooks in your Unstructured personal account, or for a workspace within an Unstructured Business account. This page describes workspace-scoped webhook actions that you can perform in the UI. You can also use the Unstructured API to perform these same actions programmatically. In addition, the API supports workflow-scoped webhooks. The API also offers the following:
  • 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.
  • Manage notifications for both workspace and workflow. 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.
  • Use the same secret-management flow described earlier for workflow-scoped webhooks, including optionally providing a secret at creation time and rotating it later through the update endpoint.
Learn more.