For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

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

Event
Description

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"

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"

Pick at least one event when you create a webhook in Settings → Webhooks. Cakewalk shows action_task.actionable as Action task ready and review_task.actionable as Review task ready. To change the label, URL or events later, select Edit in the webhook's menu.

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

Actionable task (with request metadata)

Review task (with request metadata)

Batching

Multiple events may appear in one request:


JSON Schema

Last updated

Was this helpful?