> For the complete documentation index, see [llms.txt](https://www.cakewalk.security/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.cakewalk.security/docs/human-access/open-api-and-mcp/webhooks.md).

# Webhooks

Register a webhook to receive Cakewalk events and handle the test, review\_task.actionable and action\_task.actionable payloads.

Webhooks let you subscribe to real-time events in Cakewalk and trigger external workflows.

### Setup

To register a webhook, you need to provide:

* Target URL
* Events to subscribe to
* Secret for HMAC verification

<table><thead><tr><th>Event</th><th>Description</th></tr></thead><tbody><tr><td><pre><code>action_task.actionable
</code></pre></td><td>This event is triggered when the action step of the request needs to be executed. e.g. "all the review steps are completed and the task to do the provisioning is ready to be done"</td></tr><tr><td><pre><code>review_task.actionable
</code></pre></td><td>This event is triggered when a review step of the request is waiting for a reviewer's decision. e.g. "the manager approval step is ready for the manager to approve or reject"</td></tr></tbody></table>

A new webhook subscribes to `action_task.actionable` by default. Add `review_task.actionable` to the webhook's events to receive review steps as well.

### Event envelope

Each element of the body array is an object with:

| Field       | Type     | Description                                    |
| ----------- | -------- | ---------------------------------------------- |
| `eventType` | `string` | Discriminator; determines the shape of `data`. |
| `data`      | `object` | Event-specific payload.                        |

***

### Event types

#### `test`

**Purpose:** Validates that a registered URL accepts webhook POSTs (webhook verification flow).

**`data`:**

| Field     | Type     | Notes                     |
| --------- | -------- | ------------------------- |
| `message` | `string` | Always `"Hello, World!"`. |

***

#### `action_task.actionable`

**Purpose:** When a user submits a request, the policy dictates whether it requires zero, one, or multiple review steps (for example, a manager may need to approve a "grant access request"). Once all reviews are complete, the process concludes with an "action step" where the task is executed in the third-party system (such as creating the user account in the external application). The system triggers this event when the action step is ready to be executed.

**`data`:**

| Field             | Type                       | Description                                                                        |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------- |
| `taskId`          | UUID string                | Identifier of the task.                                                            |
| `assignedTo`      | array                      | Users assigned to the task; may be empty. Each item has `id`, `email`, `fullName`. |
| `requestMetadata` | object or omitted / `null` | Context for policy-based request tasks; structure below.                           |

**`requestMetadata` (when present):**

| Field                   | Type             | Description                                                  |
| ----------------------- | ---------------- | ------------------------------------------------------------ |
| `reviewedBy`            | array of users   | Same shape as `assignedTo` items.                            |
| `requestType`           | string           | One of the policy-based request type names (see enum below). |
| `requestedBy`           | user object      | User who requested the action.                               |
| `targetWorkApp`         | object or `null` | `id` (UUID), `name` (display name).                          |
| `permissionLevel`       | object or `null` | `id` (UUID), `name`.                                         |
| `targetUser`            | user or `null`   | Subject user when applicable.                                |
| `triggeredByUsersGroup` | object or `null` | `id` (UUID), `name`.                                         |

**`requestType` possible values** (from `PolicyBasedRequestType` in domain):

* `GrantAccessRequest`
* `RemoveAccessRequest`
* `ArchiveWorkAppRequest`
* `ChangePermissionLevelRequest`
* `AddNewManagedWorkAppRequest`

***

#### `review_task.actionable`

**Purpose:** When a user submits a request, the policy may require one or more review steps before the action step (for example, a manager approving a "grant access request"). The system triggers this event each time a review step is ready for a reviewer's decision. A request with two review steps produces two events, one per step. Review steps that the policy approves automatically do not trigger the event.

**`data`:**

| Field             | Type                       | Description                                                                           |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| `taskId`          | UUID string                | Identifier of the review task.                                                        |
| `assignedTo`      | array                      | Users who can review the task; may be empty. Each item has `id`, `email`, `fullName`. |
| `requestMetadata` | object or omitted / `null` | Context for policy-based request tasks; structure below.                              |

**`requestMetadata` (when present):**

Same fields as `action_task.actionable`, without `reviewedBy`.

| Field                   | Type             | Description                                                  |
| ----------------------- | ---------------- | ------------------------------------------------------------ |
| `requestType`           | string           | One of the policy-based request type names (see enum above). |
| `requestedBy`           | user object      | User who submitted the request.                              |
| `targetWorkApp`         | object or `null` | `id` (UUID), `name` (display name).                          |
| `permissionLevel`       | object or `null` | `id` (UUID), `name`.                                         |
| `targetUser`            | user or `null`   | Subject user when applicable.                                |
| `triggeredByUsersGroup` | object or `null` | `id` (UUID), `name`.                                         |

***

### Examples

#### Test webhook

```json
[
  {
    "eventType": "test",
    "data": {
      "message": "Hello, World!"
    }
  }
]
```

#### Actionable task (with request metadata)

```json
[
  {
    "eventType": "action_task.actionable",
    "data": {
      "taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "assignedTo": [
        {
          "id": "7b9e3e2a-1111-4111-8111-111111111111",
          "email": "reviewer@example.com",
          "fullName": "Reviewer Name"
        }
      ],
      "requestMetadata": {
        "reviewedBy": [],
        "requestType": "GrantAccessRequest",
        "requestedBy": {
          "id": "8c0f4f3b-2222-4222-8222-222222222222",
          "email": "requester@example.com",
          "fullName": "Requester Name"
        },
        "targetWorkApp": {
          "id": "9d1e5a4c-3333-4333-8333-333333333333",
          "name": "Example App"
        },
        "permissionLevel": {
          "id": "ae2f6b5d-4444-4444-8444-444444444444",
          "name": "Member"
        },
        "targetUser": {
          "id": "bf3g7c6e-5555-4555-8555-555555555555",
          "email": "target@example.com",
          "fullName": "Target User"
        },
        "triggeredByUsersGroup": {
          "id": "c04h8d7f-6666-4666-8666-666666666666",
          "name": "Engineering"
        }
      }
    }
  }
]
```

#### Review task (with request metadata)

```json
[
  {
    "eventType": "review_task.actionable",
    "data": {
      "taskId": "dbedcbb0-284f-4ba3-9cba-75066fb6eb92",
      "assignedTo": [
        {
          "id": "7b9e3e2a-1111-4111-8111-111111111111",
          "email": "reviewer@example.com",
          "fullName": "Reviewer Name"
        }
      ],
      "requestMetadata": {
        "requestType": "ChangePermissionLevelRequest",
        "requestedBy": {
          "id": "8c0f4f3b-2222-4222-8222-222222222222",
          "email": "requester@example.com",
          "fullName": "Requester Name"
        },
        "targetWorkApp": {
          "id": "9d1e5a4c-3333-4333-8333-333333333333",
          "name": "Example App"
        },
        "permissionLevel": {
          "id": "ae2f6b5d-4444-4444-8444-444444444444",
          "name": "Manager"
        },
        "targetUser": {
          "id": "8c0f4f3b-2222-4222-8222-222222222222",
          "email": "requester@example.com",
          "fullName": "Requester Name"
        },
        "triggeredByUsersGroup": null
      }
    }
  }
]
```

#### Batching

Multiple events may appear in one request:

```json
[
  { "eventType": "test", "data": { "message": "Hello, World!" } },
  {
    "eventType": "action_task.actionable",
    "data": {
      "taskId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "assignedTo": [],
      "requestMetadata": null
    }
  }
]
```

***

### JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cakewalk.internal/schemas/customer-webhook-events.json",
  "title": "CakewalkCustomerWebhookEventBatch",
  "description": "JSON array POSTed to customer webhook URLs.",
  "type": "array",
  "items": { "$ref": "#/$defs/webhookEvent" },
  "$defs": {
    "uuid": {
      "type": "string",
      "format": "uuid"
    },
    "webhookUser": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "email", "fullName"],
      "properties": {
        "id": { "$ref": "#/$defs/uuid" },
        "email": { "type": "string" },
        "fullName": { "type": "string" }
      }
    },
    "webhookWorkApp": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "name"],
      "properties": {
        "id": { "$ref": "#/$defs/uuid" },
        "name": { "type": "string" }
      }
    },
    "webhookPermissionLevel": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "name"],
      "properties": {
        "id": { "$ref": "#/$defs/uuid" },
        "name": { "type": "string" }
      }
    },
    "webhookUsersGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "name"],
      "properties": {
        "id": { "$ref": "#/$defs/uuid" },
        "name": { "type": "string" }
      }
    },
    "policyBasedRequestTypeName": {
      "type": "string",
      "enum": [
        "GrantAccessRequest",
        "RemoveAccessRequest",
        "ArchiveWorkAppRequest",
        "ChangePermissionLevelRequest",
        "AddNewManagedWorkAppRequest"
      ]
    },
    "requestMetadata": {
      "type": "object",
      "additionalProperties": false,
      "required": ["reviewedBy", "requestType", "requestedBy"],
      "properties": {
        "reviewedBy": {
          "type": "array",
          "items": { "$ref": "#/$defs/webhookUser" }
        },
        "requestType": { "$ref": "#/$defs/policyBasedRequestTypeName" },
        "requestedBy": { "$ref": "#/$defs/webhookUser" },
        "targetWorkApp": {
          "anyOf": [{ "$ref": "#/$defs/webhookWorkApp" }, { "type": "null" }]
        },
        "permissionLevel": {
          "anyOf": [{ "$ref": "#/$defs/webhookPermissionLevel" }, { "type": "null" }]
        },
        "targetUser": {
          "anyOf": [{ "$ref": "#/$defs/webhookUser" }, { "type": "null" }]
        },
        "triggeredByUsersGroup": {
          "anyOf": [{ "$ref": "#/$defs/webhookUsersGroup" }, { "type": "null" }]
        }
      }
    },
    "testEventData": {
      "type": "object",
      "additionalProperties": false,
      "required": ["message"],
      "properties": {
        "message": { "type": "string", "const": "Hello, World!" }
      }
    },
    "actionTaskActionableData": {
      "type": "object",
      "additionalProperties": false,
      "required": ["taskId", "assignedTo"],
      "properties": {
        "taskId": { "$ref": "#/$defs/uuid" },
        "assignedTo": {
          "type": "array",
          "items": { "$ref": "#/$defs/webhookUser" }
        },
        "requestMetadata": {
          "anyOf": [{ "$ref": "#/$defs/requestMetadata" }, { "type": "null" }]
        }
      }
    },
    "reviewRequestMetadata": {
      "type": "object",
      "additionalProperties": false,
      "required": ["requestType", "requestedBy"],
      "properties": {
        "requestType": { "$ref": "#/$defs/policyBasedRequestTypeName" },
        "requestedBy": { "$ref": "#/$defs/webhookUser" },
        "targetWorkApp": {
          "anyOf": [{ "$ref": "#/$defs/webhookWorkApp" }, { "type": "null" }]
        },
        "permissionLevel": {
          "anyOf": [{ "$ref": "#/$defs/webhookPermissionLevel" }, { "type": "null" }]
        },
        "targetUser": {
          "anyOf": [{ "$ref": "#/$defs/webhookUser" }, { "type": "null" }]
        },
        "triggeredByUsersGroup": {
          "anyOf": [{ "$ref": "#/$defs/webhookUsersGroup" }, { "type": "null" }]
        }
      }
    },
    "reviewTaskActionableData": {
      "type": "object",
      "additionalProperties": false,
      "required": ["taskId", "assignedTo"],
      "properties": {
        "taskId": { "$ref": "#/$defs/uuid" },
        "assignedTo": {
          "type": "array",
          "items": { "$ref": "#/$defs/webhookUser" }
        },
        "requestMetadata": {
          "anyOf": [{ "$ref": "#/$defs/reviewRequestMetadata" }, { "type": "null" }]
        }
      }
    },
    "webhookEvent": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["eventType", "data"],
          "properties": {
            "eventType": { "type": "string", "const": "test" },
            "data": { "$ref": "#/$defs/testEventData" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["eventType", "data"],
          "properties": {
            "eventType": { "type": "string", "const": "action_task.actionable" },
            "data": { "$ref": "#/$defs/actionTaskActionableData" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["eventType", "data"],
          "properties": {
            "eventType": { "type": "string", "const": "review_task.actionable" },
            "data": { "$ref": "#/$defs/reviewTaskActionableData" }
          }
        }
      ]
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.cakewalk.security/docs/human-access/open-api-and-mcp/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
Event	Description
`action_task.actionable`	This event is triggered when the action step of the request needs to be executed. e.g. "all the review steps are completed and the task to do the provisioning is ready to be done"
`review_task.actionable`	This event is triggered when a review step of the request is waiting for a reviewer's decision. e.g. "the manager approval step is ready for the manager to approve or reject"