Create a Webhook

Create a notification with webhooks for events within Immuta

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.

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.

Requirement

APPLICATION_ADMIN Immuta permission

Configuration options

When creating the webhook, there are two key choices:

What events will kick off the webhook?

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. Here is a list of popular types grouped by Immuta source:

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

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

• 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

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.

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

Payload

{
  "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.

{
  "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.

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