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
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:
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:
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:
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):
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):
GrantAccessRequestRemoveAccessRequestArchiveWorkAppRequestChangePermissionLevelRequestAddNewManagedWorkAppRequest
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:
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.
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?