Generate Views with Webhooks

This document details how to externally generate native views for databases that are currently not supported as integrations in Immuta using the Immuta API, equalized projects, and webhooks.

Introduction

Immuta supports several integrations that allow users to interact directly with their systems without going through a proxy. For systems that Immuta does not currently support as an integration, users can generate native views for these systems using

• Equalized projects,

• Global webhooks, and the

• Immuta API.

The implementation of generating native views will vary based on internal business requirements; however, the general workflow and interaction with the Immuta API and webhooks are outlined below.

Webhooks

A number of webhooks ensure native views represent the current state of the policies enforced. The table below describes each of these notification types.

Register for webhook notifications

To receive webhook notifications, you must register for the notifications as a user with the APPLICATION_ADMIN permission to create a global webhook. Unlike a regular webhook, a global webhook ensures that you receive all notifications, even if they don’t pertain to the particular user who registered the hook. Note: You should only register the hook once.

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.

Determine if the webhook exists

Before registering a webhook, check if the webhook already exists by comparing it to the names and URLs of existing webhooks. If there is already a webhook with the name and url of the one you want to register, it already exists and you don't need to register it. Completing this process whenever your service starts up will ensure that you never miss notifications.

Use the request and example response provided below for guidance:

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer <TOKEN>" \
    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",
            "policyUpdated",
            "dataSourceUpdated",
            "modelCreated"
        ],
        "global": true,
        "createdBy": 21
    }
]

Register a webhook

After you have determined that the webhook does not exist, register it with the four notification types outlined in the payload example below.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer <TOKEN>" \
    --data @example-payload.json \
    https://demo.immuta.com/webhooks

{
    "webhooks": [{
        "name": "ViewMonitorHook",
        "global": true,
        "notificationType": [
            "dataSourceUpdated",
            "policyUpdated",
            "addedToProject",
            "removedFromProject"
        ],
        "url": "https://external.service.com/processWebhook"
    }]
}

Make API calls when notifications are received

Once a notification is received, additional calls need to be made to the Immuta API to ensure the native views reflect the current state of policies, data sources, and projects. These calls depend on the notification received, so the calls required for each are outlined by notification type throughout this section.

A data source has been updated

Use the tabs below for guidance when you receive the dataSourceUpdated notification.

{
    "dataSourceName": "Customer",
    "fields": { "disabled": true, "handler": "Snowflake" },
    "notificationType": "dataSourceUpdated",
    "actionBy": 1,
    "modelType": "datasource",
    "modelId": 3,
    "targetUser": 1,
    "targetGroup": null,
    "actionByName": "John Doe",
    "targetUserName": "John Doe"
}