2024.3
Search powered by AI

Manage Webhooks

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.

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

  1. Create a webhook

  2. Retrieve webhook information

  3. Retry webhook.

  4. Delete a webhook

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.

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

Payload example

{
  "webhooks": [
    {
      "url": "https://demo.service.com/processWebhook",
      "name": "ViewMonitorHook",
      "global": false,
      "notificationType": [
        "ALL_NOTIFICATIONS"
      ],
      "actionType": "triggered"
    }
  ]
}

Response example

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

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks

Response example

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

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks/actions

Response example

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

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true

Response example

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

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks/1

Response example

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

curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks/history/retry/1

Response example

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

curl \
    --request DELETE \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/webhooks/1

Response example

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

curl \
    --request GET \
    --header "Authorization: Bearer <TOKEN>" \
    https://demo.immuta.com/webhooks/history?pageSize=20&includeUser=true

Response example

{
  "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
    }
  ]
}

Last updated

Other versions

SaaS2024.22024.12023.4

Copyright © 2014-2024 Immuta Inc. All rights reserved.