Webhook Payload Structure

A webhook payload contains data about events occurring in a source system. Typically formatted as JSON, this structured information is sent to a specified URL when a predefined event triggers the webhook. Understanding the payload structure is essential for developers to process and respond to incoming webhook data effectively. This page outlines the standard format of our webhook payloads, detailing the key components in facilitating data exchange between applications.

Structure

The WebhookPayload type is defined as follows:

export type WebhookPayload = {
    cuid: string;
    event: WebhookEvent;
    targetType: WebhookTarget;
} & (WebhookTargetCuid | WebhookTargetCuids);

Fields

1. cuid (string)

   • A unique identifier for the webhook request.

   • Example: "1736201637380-0"

2. event (WebhookEvent)

   • The type of event that triggered the webhook.

   • Example: "FindingPublished"

3. targetType (WebhookTarget)

   • The type of entity associated with the event.

   • Example: "finding"

4. targetCuid or targetCuids

   • The payload will include either targetCuid or targetCuids, but never both.

   • targetCuid (string): Used for single-entity events.

     • Example: "cm4wxq2ly000a0v79f9ky0um3"

   • targetCuids (string[]): Used for multi-entity events.

     • Example: ["cm4wxq2ly000a0v79f9ky0um3", "cm5lljwdv000adbcm0vak590c"]

Example Outputs

When updating a single finding (targetCuid):

json{
  "cuid": "1736201637380-0",
  "event": "FindingPublished",
  "targetType": "finding",
  "actorCuid": "cm4vvezyh0001s779eayh03v5",
  "targetCuid": "cm4wxq2ly000a0v79f9ky0um3"
}

When bulk updating findings (targetCuids):

json{
  "cuid": "1736201533947-0",
  "event": "FindingPublished",
  "targetType": "finding",
  "actorCuid": "cm4vvezyh0001s779eayh03v5",
  "targetCuids": [
    "cm4wxq2ly000a0v79f9ky0um3",
    "cm5lljwdv000adbcm0vak590c"
  ]
}