> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/govern/detect-your-data/notifications/how-to-guides/create-a-webhook.md).

# Create a Webhook

{% hint style="info" %}
Immuta offers webhooks for events in both the Request app and the Govern app. For details about the available webhooks and setup instructions for the Request app, see the [Notifications section](/saas/request/notifications.md).
{% endhint %}

Webhooks for events in the Govern app are managed exclusively through the API. This guide will walk you through creating a webhook, explaining the key fields. For a complete list of all webhook-related API endpoints, see the [Manage webhooks page](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/webhooks.md).

**Requirement**

`APPLICATION_ADMIN` Immuta permission

## Configuration options

When creating the webhook, there are two key choices:

<details>

<summary>What events will kick off the webhook?</summary>

The events that trigger the webhook are represented by `notificationType` in the payload when creating the webhook. For a full list of the available events, see the [Webhooks reference guide](/saas/govern/detect-your-data/notifications/reference-guides/notification-events.md). Here is a list of popular types grouped by Immuta source:

| Immuta source                    | Types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| All Immuta actions and events    | `ALL_NOTIFICATIONS`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Data sources                     | <ul><li><code>dataSourceExpired</code></li><li><code>dataSourceExpiring</code></li><li><code>dataSourceUpdated</code></li><li><code>healthCheckFailed</code></li><li><code>healthCheckResolved</code></li><li><code>modelCopied</code></li><li><code>modelCreated</code></li><li><code>modelDeleted</code></li><li><code>modelTagAdded</code></li><li><code>modelTagRemoved</code></li></ul>                                                                                                                                                                                                                                                                                         |
| Domains                          | <ul><li><code>automaticDomainAssignmentFailure</code></li><li><code>collectionCreated</code></li><li><code>collectionDataSourceAdded</code></li><li><code>collectionDataSourceRemoved</code></li><li><code>collectionDeleted</code></li><li><code>collectionPermissionGranted</code></li><li><code>collectionPermissionRevoked</code></li><li><code>collectionUpdated</code></li></ul>                                                                                                                                                                                                                                                                                               |
| Policy and data access decisions | <ul><li><code>certificationRequired</code></li><li><code>conflictingGlobalPolicies</code></li><li><code>globalPolicyCreated</code></li><li><code>globalPolicyDeleted</code></li><li><code>globalPolicyDisabled</code></li><li><code>globalPolicyUpdated</code></li><li><code>modelAccessApproved</code></li><li><code>modelAccessDenied</code></li><li><code>modelAccessRequested</code></li><li><code>modelAccessRevoked</code></li><li><code>modelAccessUpdated</code></li><li><code>modelUserAdded</code></li><li><code>modelUserDeleted</code></li><li><code>modelUserJoined</code></li><li><code>policyCertificationExpired</code></li><li><code>policyUpdated</code></li></ul> |
| Projects                         | <ul><li><code>acknowledgedAccess</code></li><li><code>addedToProject</code></li><li><code>deletedDatasourceRemovedFromProject</code></li><li><code>expiredDatasourceRemovedFromProject</code></li><li><code>projectDisabled</code></li><li><code>projectEqualizationMemberNotInCompliance</code></li><li><code>projectEqualizationToggled</code></li><li><code>projectUpdated</code></li><li><code>removedFromProject</code></li></ul>                                                                                                                                                                                                                                               |
| Tags                             | <ul><li><code>tagCreated</code></li><li><code>tagDeleted</code></li><li><code>tagUpdated</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Users and user management        | <ul><li><code>attributeAdded</code></li><li><code>attributeRemoved</code></li><li><code>attributeUpdated</code></li><li><code>groupUserAdded</code></li><li><code>groupUserDeleted</code></li><li><code>permissionsUpdated</code></li><li><code>userCloned</code></li><li><code>userCreated</code></li><li><code>userDeleted</code></li><li><code>userDisabled</code></li><li><code>userEnabled</code></li><li><code>userMigrated</code></li><li><code>usernameUpdated</code></li><li><code>userUpdated</code></li></ul>                                                                                                                                                             |

</details>

<details>

<summary>Do you want a personal notification for your events or do you want a global notification to monitor all events in Immuta?</summary>

* If you just want notifications for **your events**, you should create a webhook with **your own account**.
* If you want notifications for **all events** in Immuta, you should create a webhook with **a system account**.

Ensure you understand the user creating the webhook and if they will be completing actions that should or should not trigger a webhook:

**Does the action triggering the webhook pertain to the creator of the webhook?**

`global` represents whether the action pertains to the creator of the webhook. The options for `global` are

* `true` : Webhooks will be sent for all actions, even if they to not impact the creator.
* `false` : Webhooks will only be sent out for actions that impact the creator.

**Is the action triggering the webhook done by the creator of the webhook?**

`actionType` represents whether the action was done by the creator of the webhook. The options for `actionType` are

* `triggered` : Webhooks will be sent out for actions the creator performs.
* `received` : Webhooks will be sent out for actions any other user performs.
* `null`: If `global` is set to `true`, then set actionType to `null`.

See the table below for a breakdown of the options:

| Webhook kickoff                                                                                                                                                   | global  | actionType  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- |
| Webhook triggers when **any user** performs an action **anywhere** in the application. This is the recommended setting for system accounts to capture all events. | `true`  | `null`      |
| Webhook triggers when the **creator** performs an action that **impacts themselves** (e.g., they add their data source to their domain).                          | `false` | `triggered` |
| Webhook triggers when **another user** performs an action that **impacts the creator** (e.g., another user adds a data source to the creator's domain).           | `false` | `received`  |

</details>

## New webhook creation

### Create the webhook

To create a webhook for all available events in Immuta with a system account, send the following request with the payload below.

```bash
curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/webhooks
```

**Payload**

```json
{
  "webhooks": [
    {
      "url": "https://demo.service.com/processWebhook",
      "name": "ViewMonitorHook",
      "global": true,
      "notificationType": [
        "ALL_NOTIFICATIONS"
      ],
      "actionType": null
    }
  ]
}
```

### View successful response

If the webhook was successfully created, you will receive a response similar to the following example.

```json
{
  "createdWebhooks": [
    {
      "id": 3,
      "url": "https://demo.service.com/processWebhook",
      "name": "ViewMonitorHook",
      "global": true,
      "actionType": null,
      "createdBy": 2,
      "createdAt": "2021-10-15T15:22:10.079Z",
      "updatedAt": "2021-10-15T15:22:10.079Z"
    }
  ],
  "errors": []
}
```

### Receive webhooks from Immuta actions

Then, when the event is triggered, you will receive a webhook similar to this example.

```json
 {
    "id": 15,
    "name": "ViewMonitorHook",
    "url": "organization.immuta.com",
    "notificationType": [
      "policyUpdated"
    ],
    "global": true,
    "createdBy": 2,
    "actionType": null
  }
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.immuta.com/saas/govern/detect-your-data/notifications/how-to-guides/create-a-webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.