# Manage Webhooks
Webhooks notify users or other systems when actions happen in Immuta. Every action that generates a notification is available as a webhook.
This page lists the REST endpoints for managing webhooks and provides examples of requests.
## Webhook overview
Application Admins can configure webhooks that are triggered by events that happen in the system (such as when data sources or projects are created), but any user can configure webhooks that are triggered by access requests and activity notifications.
All user-configured webhook integrations must respond within 10 seconds of receiving the webhook request payload. If the webhook integration takes longer to respond, the [request will timeout](#timed-out-request).
## Webhook workflow
1. [Create a webhook](#create-a-webhook)
2. [Retrieve webhook information](#retrieve-webhook-information)
3. [Retry webhook](#retry-webhook-by-id).
4. [Delete a webhook](#delete-a-webhook)
## Create a webhook
`POST` `/webhooks`
Create a new webhook. Users can create multiple webhooks in a single request.
#### Webhook Notifications
| Type | Triggers |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| acknowledgedAccess | A project member acknowledges the purposes on a project. |
| addedToProject | A data source is added to a project. |
| apiKeyRevoked | A user's API key is revoked. |
| attributeAdded | An attribute is added to a group or user. |
| attributeRemoved | An attribute is removed from a group or user. |
| attributeUpdated | Attributes for a group or user are updated. |
| bulkJobStatus | A bulk action is completed (whether success/failure). |
| certificationRequired | A Global Policy that requires certification by the data source owner is applied to a data source. |
| conflictingGlobalPolicies | Global Policies are applied to the same column on a data source. |
| dataSourceExpired | A data source that was configured to expire has expired. |
| dataSourceExpiring | A data source that was configured to expire expires tomorrow. |
| dataSourceUpdated | A data source is updated. |
| deletedDatasourceRemovedFromProject | A data source has been deleted and then removed from a project. |
| expiredDatasourceRemovedFromProject | A data source that has expired and been deleted is removed from a project. |
| firstQuery | A data source is queried for the first time through Immuta. |
| globalPolicyCreated | A Global Policy is created. |
| globalPolicyDeleted | A Global Policy is deleted. |
| globalPolicyDisabled | A Global Policy is disabled. |
| globalPolicyUpdated | A Global Policy is updated. |
| groupUserAdded | A user is added to a group. |
| groupUserDeleted | A user is removed from a group. |
| healthCheckFailed | A health check runs and returns not healthy. |
| healthCheckResolved | A health check runs and returns healthy. |
| modelAccessApproved | A user's access request is approved for a data source or project. |
| modelAccessDenied | A user's access request is denied for a data source or project. |
| modelAccessRequested | A user requests access to a data source or project. |
| modelAccessRevoked | A user's access request is revoked for a data source or project. |
| modelAccessUpdated | A user's access level is updated for a data source or project. |
| modelCreated | A data source or project is created. |
| modelDeleted | A data source or project is deleted. |
| modelTagAdded | A tag is added to a data source or a data source column. |
| modelTagRemoved | A tag is removed from a data source or a data source column. |
| modelUserAdded | A user is added to a data source. |
| modelUserDeleted | A user is removed from a data source. |
| modelUserJoined | A user joins a data source that they are already allowed to join. |
| nativeWorkspaceStateChanged | A native workspace configuration within a project changes. |
| permissionsUpdated | A user's permissions are updated. |
| policyAdjustmentCreated | A policy adjustment is created. |
| policyAdjustmentExpired | A policy adjustment has expired (the default is after a year). |
| policyCertificationExpired | A policy certification on a data source has expired. |
| policyUpdated | A data source's policies have been updated by a user or Global Policy. Policy updates are triggered for many reasons, including when a data source is created, a user updates them, a Global Policy changed, tags are added to a data source or column, the data dictionary changed, a fingerprint is recomputed, an external catalog modifies tags on a linked data source, or a policy disabled. |
| projectDisabled | A project is disabled. |
| projectEqualizationMemberNotInCompliance | A member of an equalized project is out of compliance. |
| projectEqualizationToggled | Project equalization is toggled on or off. |
| projectUpdated | A project is updated. |
| purposeCreated | A purpose is created. |
| purposeDeleted | A purpose is deleted. |
| purposeUpdated | A purpose is updated. |
| queryCanceled | A running query is canceled due to a change on a data source. |
| queryCreated | A user creates a public query on a data source. |
| queryUpdated | A public query is updated. |
| removedFromProject | A data source is removed from a project. |
| switchedCurrentProject | A user switches their current project. |
| tagCreated | A tag is created. |
| tagDeleted | A tag is deleted. |
| tagUpdated | A tag is updated. |
| taskDeleted | An outstanding data source task is deleted without validation. |
| taskValidated | An outstanding data source task is validated. |
| userCloned | A user is cloned. |
| userCreated | A user or group is created. |
| userDeleted | A user or group is deleted. |
| userDisabled | A user is disabled. |
| userEnabled | A user is enabled. |
| userMigrated | A user is migrated from an old IAM to a new IAM. |
| usernameUpdated | A user's name is updated. |
| userUpdated | A group is updated. |
#### Payload parameters
| Attribute | Description | Required |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| webhooks | `array[object]` The details for each webhook you would like to create including the values for `url`, `name`, `global`, `notificationType`, `actionType`, and `secret`. | **Yes** |
| url | `string` URL for outbound webhook request. | **Yes** |
| name | `string` The webhook's name. | **Yes** |
| global | `boolean` If `true`, you will receive all notifications even if they do not pertain to you. | **Yes** |
| notificationType | `array` A list of the webhook notifications you would like to receive. | **Yes** |
| actionType | `string` The options are `triggered` or `receive`. | **Yes** |
| secret | `string` Shared secret for computing the webhook signature. This webhook signature must be verified by `SHA1`. | No |
#### Response schema
| Attribute | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| createdWebhooks | `array[object]` Details on each webhook that was created including values for `id`, `url`, `name`, `global`, `actionType`, and the date it was created. |
### Request example
The following request with the payload below creates a new webhook.
```shell
curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/webhooks
```
#### Payload example
```json
{
"webhooks": [
{
"url": "https://demo.service.com/processWebhook",
"name": "ViewMonitorHook",
"global": false,
"notificationType": [
"ALL_NOTIFICATIONS"
],
"actionType": "triggered"
}
]
}
```
### Response example
```json
{
"createdWebhooks": [
{
"id": 3,
"url": "https://demo.service.com/processWebhook",
"name": "ViewMonitorHook",
"global": false,
"actionType": "triggered",
"createdBy": 2,
"createdAt": "2021-10-15T15:22:10.079Z",
"updatedAt": "2021-10-15T15:22:10.079Z"
}
],
"errors": []
}
```
## Retrieve webhook information
| Endpoint | Purpose |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [`/webhooks`](#search-for-webhooks) | Return a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.) |
| [`/webhooks/actions`](#search-for-notification-actions) | Return a list of valid notification actions that a webhook can be triggered by. |
| [`/webhooks/history`](#search-for-webhook-records) | Return historical records for webhook requests, including requests and responses. |
| [`/webhooks/{id}`](#search-for-webhook-by-id) | Return specified webhook by ID. |
### Search for webhooks
`GET` `/webhooks`
Return a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.)
#### Response schema
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| value | `metadata` Details regarding the returned list of webhooks including, `id`, `name`, `url`, `notificationType`, `global`, and `createdBy`. |
#### Request example
The following request returns a list of webhooks the user can see.
```shell
curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks
```
#### Response example
```json
{
"id": 1,
"name": "internal-automatic-subscription-webhook",
"url": "/internal-webhook/automatic-subscription",
"notificationType": [
"groupUserAdded",
"groupUserDeleted",
"attributeAdded",
"attributeRemoved",
"attributeUpdated",
"userDeleted",
"userMigrated",
"userCreated",
"policyUpdated",
"dataSourceUpdated",
"modelCreated"
],
"global": true,
"createdBy": 1
}
```
### Search for notification actions
`GET` `/webhooks/actions`
Return a list of valid notification actions that a webhook can be triggered by. |
#### Response schema
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------- |
| value | `metadata` Details regarding the list of actions that a webhook can be created for. |
#### Request example
The following request returns a list of valid notification actions that a webhook can be triggered by.
```shell
curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/actions
```
#### Response example
```json
[
"ALL_NOTIFICATIONS",
"modelCreated",
"modelDeleted",
"modelCopied",
"dataSourceUpdated",
"dataSourceExpired",
"dataSourceExpiring",
"healthCheckFailed",
"healthCheckResolved",
"modelUserAdded",
"modelUserDeleted",
"modelUserJoined",
"modelAccessRequested",
"modelAccessApproved",
"modelAccessRevoked",
"modelAccessUpdated",
"modelAccessDenied",
"modelTagAdded",
"modelTagRemoved",
"projectUpdated",
"projectEqualizationToggled",
"projectEqualizationMemberNotInCompliance",
"projectDisabled",
"addedToProject",
"removedFromProject",
"deletedDatasourceRemovedFromProject",
"expiredDatasourceRemovedFromProject",
"updatedModelInProject",
"nativeWorkspaceStateChanged",
"policyUpdated",
"queryCreated",
"queryCanceled",
"queryUpdated",
"firstQuery",
"userCreated",
"userDeleted",
"userEnabled",
"userCloned",
"userDisabled",
"userMigrated",
"groupUserAdded",
"groupUserDeleted",
"userUpdated",
"attributeUpdated",
"attributeAdded",
"attributeRemoved",
"permissionsUpdated",
"switchedCurrentProject",
"usernameUpdated",
"acknowledgedAccess",
"purposeCreated",
"purposeUpdated",
"purposeDeleted",
"tagCreated",
"tagUpdated",
"tagDeleted",
"governanceSettingsUpdated",
"apiKeyRevoked",
"conflictingGlobalPolicies",
"globalPolicyCreated",
"globalPolicyUpdated",
"globalPolicyDeleted",
"globalPolicyDisabled",
"bulkJobStatus",
"taskValidated",
"taskDeleted",
"certificationRequired",
"policyCertificationExpired",
"policyAdjustmentExpired",
"policyAdjustmentCreated"
]
```
[View Webhook Notifications](#create-a-webhook)
### Search for webhook records
`GET` `/webhooks/history`
Return historical records for webhook requests, including requests and responses.
#### Query parameters
| Attribute | Description | Required |
| ---------------- | ------------------------------------------------------------------------------------------------------ | -------- |
| offset | `integer` The number of records to skip for this query. | No |
| pageSize | `integer` The number of records to return in this query. **The default is `20`**. | No |
| sortField | `string` The field to use for sorting. **The default is `createdAt`.** | No |
| sortOrder | `string` The sort order to use. **The default is `desc`**. | No |
| notificationType | `string` If set will only return activities of this type. | No |
| includeGlobal | `boolean` If `true`, global records will be included. | No |
| includeUser | `boolean` If `true`, personal webhooks will be returned for the given user. **The default is `true`**. | No |
| successOrFailure | `string` If set will only retrieve records that were successful or failed. | No |
#### Response schema
| Attribute | Description |
| --------- | ------------------------------------------------ |
| count | `integer` The number of results for the request. |
| records | `metadata` Details on each webhook result. |
#### Request example
The following request returns historical records for webhook requests, including requests and responses.
```shell
curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true
```
#### Response example
```json
{
"count": "0",
"records": []
}
```
### Search for webhook by ID
`GET` `/webhooks/{id}`
Return specified webhook by ID.
#### Query parameters
| Attribute | Description | Required |
| --------- | ------------------------ | -------- |
| id | `string` The webhook ID. | **Yes** |
#### Response schema
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| value | `metadata` Details regarding the returned list of webhooks including, `id`, `name`, `url`, `notificationType`, `global`, and `createdBy`. |
#### Request example
The following request returns details on the webhook with the ID `1`.
```shell
curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1
```
#### Response example
```json
{
"id": 1,
"name": "internal-automatic-subscription-webhook",
"url": "/internal-webhook/automatic-subscription",
"notificationType": [
"groupUserAdded",
"groupUserDeleted",
"attributeAdded",
"attributeRemoved",
"attributeUpdated",
"userDeleted",
"userMigrated",
"userCreated",
"policyUpdated",
"dataSourceUpdated",
"modelCreated"
],
"global": true,
"createdBy": 1
}
```
## Retry webhook by ID
`POST` `/webhooks/history/retry/{id}`
Retry webhook requests by history ID. This can be done against any history record, regardless of failure or success.
#### Query parameters
| Attribute | Description | Required |
| --------- | -------------------------------------------- | -------- |
| id | `integer` ID of the history record to retry. | **Yes** |
#### Response schema
| Attribute | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| id | `integer` The ID of the history record. |
| request | `array` Details on the request, including values for `test`, `metadata`, `webhookId`, and `webhookName`. |
| response | `array` Details on the response. |
| statusCode | `integer` The status code for the webhook. *A value of `200` is successful.* |
| notificationType | `string` The type of notification. |
| webhooksActivityId | `integer` The ID for the activity. |
| createdAt | `timestamp` The date the webhook was created. |
| updatedAt | `timestamp` The date the webhook was last updated. |
### Request example
The following request retries the webhook with the ID `1`.
```shell
curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history/retry/1
```
### Response example
```json
{
"id": 228,
"request": {
"text": "Katie has created the Public (https://demo.example.com/#/project/1) project. Please click here (https://demo.example.com/#/project/1) for additional information.",
"metadata": {
"modelId": 1,
"actionBy": 2,
"modelType": "project",
"targetUser": 2,
"projectName": "Public",
"targetGroup": null,
"actionByName": "Katie",
"targetUserName": "Katie",
"notifyInitiator": true,
"notificationType": "modelCreated"
},
"webhookId": 1,
"webhookName": "internal-automatic-subscription-webhook"
},
"response": {},
"statusCode": 200,
"notificationType": "modelCreated",
"webhooksActivityId": 11,
"createdAt": "2021-10-15T16:44:06.872Z",
"updatedAt": "2021-10-15T16:44:06.872Z"
}
```
## Delete a webhook
`DELETE` `/webhooks/{id}`
Delete a webhook by ID.
#### Query parameters
| Attribute | Description | Required |
| --------- | ------------------------- | -------- |
| id | `integer` The webhook ID. | **Yes** |
#### Response schema
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| value | `metadata` Details regarding the webhook, `id`, `url`, `name`, `global`, `actionType`, `createdBy`, `createdAt`, `updatedAt`. |
### Request example
The following request deletes the webhook with the ID `1`.
```shell
curl \
--request DELETE \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1
```
### Response example
```json
{
"id": 1,
"url": "/internal-webhook/automatic-subscription",
"name": "internal-automatic-subscription-webhook",
"global": true,
"actionType": null,
"createdBy": 1,
"createdAt": "2021-06-24T15:08:58.906Z",
"updatedAt": "2021-06-24T15:08:58.906Z"
}
```
## Troubleshooting
| statusCode | code | Issue |
| ---------- | ------------------------------------------------------------------------ | ---------------------- |
| `500` | [`ESOCKETTIMEDOUT`](#timed-out-request) | The request timed out. |
### Timed out request
The webhook request took longer than Immuta allows for a response. The default time limit is 10 seconds. To change this limit, reach out to your Immuta representative.
#### Request example
```shell
curl \
--request GET \
--header "Authorization: Bearer " \
https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true
```
#### Response example
```json
{
"count": "1",
"records": [
{
"id": 1,
"request": {
"text": "You have created the sheep man project. Please click here (http://immuta.demo.com/#/project/11) for additional information.",
"metadata": {
"modelId": 11,
"actionBy": 1,
"modelType": "project",
"targetUser": 1,
"projectName": "sheep man",
"targetGroup": null,
"actionByName": "Jane Doe",
"targetUserName": "Jane Doe",
"notificationType": "modelCreated"
},
"webhookId": 2,
"webhookName": "webhook"
},
"response": {
"body": {
"code": "ESOCKETTIMEDOUT",
"connect": false
}
},
"statusCode": 500,
"notificationType": "modelCreated",
"webhooksActivityId": 15,
"createdAt": "2022-06-01T17:05:34.001Z",
"updatedAt": "2022-06-01T17:05:34.001Z",
"webhooksId": 2,
"url": "http://localhost:8080/webhook",
"name": "webhook",
"actionType": null,
"createdBy": 1
}
]
}
```
---
# Agent Instructions: 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:
```
GET https://documentation.immuta.com/saas/~/changes/l3NnvynMHxi6VvqRtJhK/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/webhooks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.