Webhooks

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

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

---

Examples

Test webhook

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

Actionable task (with request metadata)

[
  {
    "eventType": "action_task.actionable",
    "data": {
      "taskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "assignedTo": [
        {
          "id": "7b9e3e2a-1111-4111-8111-111111111111",
          "email": "[email protected]",
          "fullName": "Reviewer Name"
        }
      ],
      "requestMetadata": {
        "reviewedBy": [],
        "requestType": "GrantAccessRequest",
        "requestedBy": {
          "id": "8c0f4f3b-2222-4222-8222-222222222222",
          "email": "[email protected]",
          "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": "[email protected]",
          "fullName": "Target User"
        },
        "triggeredByUsersGroup": {
          "id": "c04h8d7f-6666-4666-8666-666666666666",
          "name": "Engineering"
        }
      }
    }
  }
]

Batching

Multiple events may appear in one request:

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

---

JSON Schema

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