Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.unstructured.io/llms.txt

Use this file to discover all available pages before exploring further.

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. The following 3-minute video provides an overview of webhooks.
The following 6-minute video shows how to use the Unstructured API to work with webhooks:
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. 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 that is associated with its target workflow 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 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.
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 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):
  • 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.

​
Verify webhook requests

Your receiver application can verify incoming webhook requests to check that the payload originated from Unstructured and was not tampered with in transit. Use the webhook secret to verify incoming requests. If you suspect that the secret has been compromised, rotate it to a new value. The following Python example reads the webhook ID, timestamp, and signature from the request headers and checks that the timestamp is within an acceptable time window. Next, it recomputes the expected HMAC-SHA256 signature from the webhook ID, timestamp, and raw request body using the notification channel secret. It then compares the computed signature to the versioned signature in the request header. If the values match, the request can be trusted as originating from Unstructured and as not having been tampered with in transit. 
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")
Use the raw request body exactly as received, not a re-serialized JSON payload. Using a re-serialized payload can cause signature verification to fail.

​
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. 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:
  1. If you do not already have an Unstructured account, sign up for free. After you sign up, you are automatically signed in to your new Unstructured Let’s Go account, at https://platform.unstructured.io.
    To sign up for a Business account instead, contact Unstructured Sales, or learn more.
  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.
    For other types of Business accounts, see your Unstructured account administrator for sign-in instructions, or email Unstructured Support at 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.
    b. Copy the value of Unstructured API Endpoint to your system’s clipboard.
To get your Unstructured API key, do the following:
  1. If you do not already have an Unstructured account, sign up for free. After you sign up, you are automatically signed in to your new Unstructured Let’s Go account, at https://platform.unstructured.io.
    To sign up for a Business account instead, contact Unstructured Sales, or learn more.
  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.
    For other types of Business accounts, see your Unstructured account administrator for sign-in instructions, or email Unstructured Support at support@unstructured.io.
  3. Get your Unstructured API key:
     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 create an API key for. Each API key works with one and only one organizational workspace. Learn more.
    b. Click Generate API Key.
    c. Follow the on-screen instructions to finish generating the key.
    d. Click the Copy icon next to your new key to add the key to your system’s clipboard. If you lose this key, simply return and click the Copy icon again.
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!
For more information on workspace-level webhook operations, see Notifications. For more information on workflow-level webhook operations, see Workflows.