> For the complete documentation index, see [llms.txt](https://docs.datasaur.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasaur.ai/integrations/webhook-notifications.md).

# Webhook Notifications

## Receive notifications via webhook

Datasaur provides webhooks to notify your application when an event happens in your labeling projects. Webhooks are useful for automation in your machine learning projects. For example, you can use a webhook to feed the data directly into your model right after labelers complete their projects.

To start using webhooks, follow these steps:

1. Prepare a POST REST API endpoint on your server that is ready to receive requests from Datasaur.
2. Register the endpoint with Datasaur. For this you will need to contact <support@datasaur.ai>. .

### Setting up a webhook

1. Open your workspace and go to **Settings > Webhooks**.

   <figure><img src="/files/sV963kVmivhRUoYHX71S" alt=""><figcaption></figcaption></figure>
2. Click **New webhook**.

   <figure><img src="/files/x0ZY3dOfW4rdayaONscM" alt=""><figcaption></figcaption></figure>
3. Configure the webhook:

   * **URL**: The endpoint that Datasaur will call. This field is required, and each webhook can have one URL.
   * **Events**: Select one or more events to subscribe to. See the [List of events](#list-of-events) for available options.
   * **Secret** *(optional)*: Used to generate the `X-Datasaur-Signature` header, allowing your endpoint to verify that requests genuinely came from Datasaur. See Webhook Signature.
   * **Custom header** *(optional)*: A header that Datasaur will include with every request sent to this endpoint. See Custom Headers.

   <figure><img src="/files/ON7tRM0TlL8kS7oN1M6K" alt=""><figcaption></figcaption></figure>
4. Click **Create**. Your webhook becomes active immediately and starts receiving the events you selected.

   <figure><img src="/files/BjyADgZOjlXh5NJQ4s2Q" alt=""><figcaption></figcaption></figure>

You can create multiple webhooks in the same workspace, each with its own URL, events, secret, and custom header. For example, you can set up separate endpoints for your staging and production environments.

{% hint style="info" %}
**Note:** Only workspace owners and admins can view or manage the **Webhooks** page. Other roles will not see it under **Settings**.
{% endhint %}

<figure><img src="/files/U460Yemnhm1HAraxcowS" alt=""><figcaption></figcaption></figure>

### Managing your webhooks

From the **Webhooks** page, each webhook appears as a card showing its URL, subscribed events, and whether a secret or custom header is configured.

* **View detail**: View the full configuration in read-only mode. The secret is always masked.
* **Edit**: Update the URL, events, secret, or custom header. If you leave the secret field empty, the existing secret will be retained. The existing secret is never pre-filled or displayed in plain text.
* **Enable / Disable**: Temporarily pause a webhook without losing its configuration, then re-enable it when needed.
* **Delete**: Permanently remove a webhook you no longer need.
* **Test**: Send a manual test delivery to the endpoint to confirm that it is reachable and configured correctly before relying on it. Webhooks that were previously configured for you by Datasaur Support will also appear here automatically. No migration is required.

### List of events

Datasaur provides a number of events that you can listen to and leverage.

* Project lifecycle
  * **Project created:** This event will be triggered when a new project is created, or when new documents are added to an existing project.
  * **Project labeled:** This event will be triggered when a labeler marks the project as complete in Labeler mode.
  * **Project reviewed:** This event will be triggered when a reviewer marks the project as complete in Reviewer mode.
* Document lifecycle
  * **Document completed:** This event will be triggered when a labeler marks a document as complete in labeler mode or when a reviewer marks a document as complete in Reviewer mode.
* Label lifecycle
  * **Before label update:** This event will be triggered just before the labeler apply a new label or update an existing label.