Webhooks API reference guide
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.
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.
.
POST /webhooks
Create a new webhook. Users can create multiple webhooks in a single request.
Required Immuta permission: APPLICATION_ADMIN
The following event types can be used to configure a webhook.
The following request with the payload below creates a new webhook.
GET /webhooks
Return a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.)
Required Immuta permission: APPLICATION_ADMIN
The following request returns a list of webhooks the user can see.
GET /webhooks/actions
Return a list of valid notification actions that a webhook can be triggered by.
Required Immuta permission: APPLICATION_ADMIN
Returns the list of notifications that can trigger a webhook. See the for descriptions.
The following request returns a list of valid notifications that can trigger a webhook.
See the table for descriptions of these notifications.
GET /webhooks/history
Return historical records for webhook requests, including requests and responses.
Required Immuta permission: APPLICATION_ADMIN
The following request returns historical records for webhook requests, including requests and responses.
GET /webhooks/{id}
Return specified webhook by ID.
Required Immuta permission: APPLICATION_ADMIN
The following request returns details on the webhook with the ID 1.
POST /webhooks/history/retry/{id}
Retry webhook requests by history ID. This can be done against any history record, regardless of failure or success.
Required Immuta permission: APPLICATION_ADMIN
The following request retries the webhook with the ID 1.
DELETE /webhooks/{id}
Delete a webhook by ID.
Required Immuta permission: APPLICATION_ADMIN
The following request deletes the webhook with the ID 1.
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.
webhooks.notificationType
array A list of the webhook notifications you would like to receive.
Yes
webhooks.actionType
string Specifies when to start the webhook. The options are triggered or received. When this attribute is set to triggered, the webhook will execute when the user who registered the webhook triggered the event. If this attribute is set to received, the webhook will execute if the user who registered the webhook receives an event triggered by another user.
Yes
webhooks.secret
string Shared secret for computing the webhook signature using HMAC authentication.
Once this field is configured, webhooks sent by Immuta will include a x-immuta-webhook-signature header that contains an HMAC digest created using :
Use SHA-1 and the shared secret you configured to verify the webhook signature.
No
Attributes for a group or user are updated.
automaticDomainAssignmentFailure
Automatically assigning a data source to a domain using a tag has failed.
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.
collectionCreated
A domain is created.
collectionDataSourceAdded
A data source is added to a domain.
collectionDataSourceRemoved
A data source is removed from a domain.
collectionDeleted
A domain is deleted.
collectionPermissionGranted
A domain permission has been assigned to a user.
collectionPermissionRevoked
A domain permission has been removed from a user.
collectionUpdated
A domain was updated.
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.
frameworkCreated
A classification framework was created.
frameworkDeleted
A classification framework was deleted.
frameworkUpdated
A classification framework was updated.
globalPolicyApprovalRescinded
A governor has removed their approval of a global policy.
globalPolicyApproved
A governor has approved a global policy.
globalPolicyChangeRequested
A governor has requested changes to a global policy.
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.
modelCopied
A data source or project is copied.
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.
nativeIntegrationValidationFailed
A validation test for an enabled integration has failed.
permissionsUpdated
A user's permissions are updated.
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 (only available for Snowflake data sources), 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.
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.
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
createdAt
timestamp The date the webhook was created.
updatedAt
timestamp The date the webhook was last updated.
createdAt
timestamp The date and time the webhook was created.
updatedAt
timestamp The date and time the webhook was last updated.
webhooks
array[object] The details for each webhook you would like to create. Its child attributes are described below.
Yes
webhooks.url
string URL for outbound webhook request.
Yes
webhooks.name
string The webhook's name.
Yes
webhooks.global
boolean If true, you will receive all notifications even if they do not pertain to you.
ALL_NOTIFICATIONS
Configures the webhook to be triggered by any event type.
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.
createdWebhooks
array[object] Details on each webhook that was created including values for id, url, name, global, actionType, and the date it was created.
Return a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.)
Return a list of valid notification actions that a webhook can be triggered by.
Return historical records for webhook requests, including requests and responses.
Return specified webhook by ID.
id
integer The ID of the webhook.
url
string URL for outbound webhook request.
name
string The webhook's name.
global
boolean If true, you will receive all notifications even if they do not pertain to you.
notificationType
array A list of the notification types included in the webhook. See the table above for a list of possible values.
createdBy
integer The ID of the user who created the webhook.
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.
count
integer The number of results for the request.
records
metadata Details on each webhook result.
id
string The webhook ID.
Yes
id
integer The ID of the webhook.
url
string URL for outbound webhook request.
name
string The webhook's name.
global
boolean If true, you will receive all notifications even if they do not pertain to you.
notificationType
array A list of the notification types included in the webhook. See the table above for a list of possible values.
createdBy
integer The ID of the user who created the webhook.
id
integer ID of the history record to retry.
Yes
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.
id
integer The webhook ID.
Yes
id
integer The ID of the webhook.
url
string URL for outbound webhook request.
name
string The webhook's name.
global
boolean If true, you will receive all notifications even if they do not pertain to you.
notificationType
array A list of the notification types included in the webhook. See the table above for a list of possible values.
createdBy
integer The ID of the user who created the webhook.
500
The request timed out.
Yes
attributeUpdated
No
curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/webhooks{
"webhooks": [
{
"url": "https://demo.service.com/processWebhook",
"name": "ViewMonitorHook",
"global": false,
"notificationType": [
"ALL_NOTIFICATIONS"
],
"actionType": "triggered"
}
]
}{
"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": []
} {
"id": 15,
"name": "Policy updated",
"url": "organization.immuta.com",
"notificationType": [
"policyUpdated"
],
"global": false,
"createdBy": 2,
"actionType": "triggered"
}curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks{
"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
}curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/actions[
"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",
"nativeIntegrationValidationFailed",
"policyUpdated",
"queryCanceled",
"firstQuery",
"userCreated",
"userDeleted",
"userEnabled",
"userCloned",
"userDisabled",
"userMigrated",
"groupUserAdded",
"groupUserDeleted",
"userUpdated",
"attributeUpdated",
"attributeAdded",
"attributeRemoved",
"permissionsUpdated",
"switchedCurrentProject",
"usernameUpdated",
"acknowledgedAccess",
"purposeCreated",
"purposeUpdated",
"purposeDeleted",
"tagCreated",
"tagUpdated",
"tagDeleted",
"apiKeyRevoked",
"conflictingGlobalPolicies",
"globalPolicyCreated",
"globalPolicyUpdated",
"globalPolicyDeleted",
"globalPolicyDisabled",
"bulkJobStatus",
"taskValidated",
"taskDeleted",
"certificationRequired",
"policyCertificationExpired"
]curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true{
"count": "0",
"records": []
}curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1{
"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
}curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history/retry/1{
"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"
}curl \
--request DELETE \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1{
"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"
}curl \
--request GET \
--header "Authorization: Bearer <TOKEN>" \
https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true{
"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
}
]
}createHmac('sha1', decryptedSecret).update(JSON.stringify(data)).digest('hex')