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 .
Webhook workflow
Create a webhook
POST
/webhooks
Create a new webhook. Users can create multiple webhooks in a single request.
Webhook Notifications
Payload parameters
Response schema
Request example
The following request with the payload below creates a new webhook.
Copy curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/webhooks
Payload example
Copy {
"webhooks" : [
{
"url" : "https://demo.service.com/processWebhook" ,
"name" : "ViewMonitorHook" ,
"global" : false ,
"notificationType" : [
"ALL_NOTIFICATIONS"
] ,
"actionType" : "triggered"
}
]
}
Response example
Copy {
"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
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
Request example
The following request returns a list of webhooks the user can see.
Copy curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks
Response example
Copy {
"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
Request example
The following request returns a list of valid notification actions that a webhook can be triggered by.
Copy curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/actions
Response example
Copy [
"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
Search for webhook records
GET
/webhooks/history
Return historical records for webhook requests, including requests and responses.
Query parameters
Response schema
Request example
The following request returns historical records for webhook requests, including requests and responses.
Copy curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history?pageSize= 20 & includeUser = true
Response example
Copy {
"count" : "0" ,
"records" : []
}
Search for webhook by ID
GET
/webhooks/{id}
Return specified webhook by ID.
Query parameters
Response schema
Request example
The following request returns details on the webhook with the ID 1
.
Copy curl \
--request GET \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1
Response example
Copy {
"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
Response schema
Request example
The following request retries the webhook with the ID 1
.
Copy curl \
--request POST \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/history/retry/1
Response example
Copy {
"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
Response schema
Request example
The following request deletes the webhook with the ID 1
.
Copy curl \
--request DELETE \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/webhooks/1
Response example
Copy {
"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
Timed out request
The webhook request took longer than Immuta allows for a response. The default is 10 seconds, but this can be configured from the Apps Settings page .
Request example
Copy curl \
--request GET \
--header "Authorization: Bearer <TOKEN>" \
https://demo.immuta.com/webhooks/history?pageSize= 20 & includeUser = true
Response example
Copy {
"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
}
]
}