Managing Webhooks

Audience: All Immuta users

Content Summary: Webhooks notify users or other systems when actions happen in Immuta. Every action that generates a notification is available as a webhook.

Application Admins can create webhooks that are triggered by events that happens in the system (such as when data sources or projects are created), but any user can create webhooks that are triggered by access requests and activity notifications.

This page lists the REST endpoints for managing webhooks and provides examples of requests.

Webhook Endpoints

Method	Path	Description
DELETE	`/webhooks/{id}`	Deletes a specific webhook by id and deletes the history records for that webhook.
GET	`/webhooks`	Returns a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.)
GET	`/webhooks/actions`	Returns a list of valid notification actions that a webhook can be triggered by.
GET	`/webhooks/history`	Returns historical records for webhook requests, including requests and responses.
GET	`/webhooks/{id}`	Returns specified webhook by id.
POST	`/history/retry/{id}`	Retries webhook requests by history id. This can be done against any history record, regardless of failure or success.
POST	`/webhooks`	Creates a new webhook. Users can create multiple webhooks in a single request.

Sample Requests

POST /webhooks:

This sample request creates a webhook that notifies the user of all activity in Immuta:

{
    "webhooks": [{
        "url": "https://my.webhook.url",
        "name": "My Webhook",
        "notificationType": ["ALL_NOTIFICATIONS"],
        "global": true
    }]
}

Note: Any number of notification types can be provided; “ALL_NOTIFICATIONS” is a dummy type that can be used to listen on all notifications).

Outbound Webhook Request:

This sample outbound webhook request is for the deletion of a data source named “Test”:

{
    "text": "Steve Touw has deleted the test data source.",
    "attachments": [{
        "text": "{\"dataSourceName\":\"test\",\"notificationType\":\"modelCreated\",\"actionBy\":1,\"modelType\":\"datasource\",\"modelId\":15,\"targetUser\":1,\"targetGroup\":null}"
    }]
}

Immuta Webhooks in Slack

Generate an Incoming Webhook URL in Slack using their detailed instructions. In Slack, set the Incoming Webhook with a name and image; it should be directed to a channel.
Using the Incoming URL generated in the previous step, create the webhook by sending a POST request to the /webhooks endpoint or going to your Immuta API page(<your-immuta-url>.com/#/api) and clicking Post '/webhooks'. Fill in the body section with the example data:

{
    "webhooks": [{
        "url": "https://my.webhook.url",
        "name": "My Webhook",
        "notificationType": ["ALL_NOTIFICATIONS"],
        "global": true
    }]
}

Then select **Try it out!** to create the webhook.

Note: There are a number of notification types (available at the /webhooks/actions endpoint), but you may want to start with "ALL_NOTIFICATIONS" and then make adjustments based on your needs.