Webhook Payload Structure

A webhook payload contains data about events 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 processing and responding effectively to incoming webhook data.

This page outlines the standard format of our webhook payloads and details the key components that facilitate data exchange between applications.

Structure

The WebhookPayload type is defined as follows:

type WebhookPayload = {
    cuid: string;
    actorCuid: string;
    event: string;
    targetCuid: string | never;
    targetCuids: string[] | never;
    targetType: string;
    text: string;
}

Security

To ensure the integrity and authenticity of webhook payloads, PlexTrac includes a X-Authorization-HMAC-256 header in the webhook request. This header contains an HMAC-SHA256 signature generated using a secret key configured when the webhook was created.

Users can verify the payload's authenticity by calculating the HMAC-SHA256 signature on their end and comparing it to the value in the X-Authorization-HMAC-256 header. For detailed instructions on how to verify the signature, users should refer to the main Webhooks documentation page.

Field Definitions

• cuid: A unique identifier for the webhook request.

• actorCuid: A string representing the unique identifier of the actor or user who triggered the event.

• event: A string indicating the type of event that triggered the webhook.

• targetCuid: A string representing the unique identifier of a single entity associated with the event. This field is mutually exclusive with targetCuids.

• targetCuids: An array of strings representing the unique identifiers of multiple entities associated with the event. This field is mutually exclusive with targetCuid.

• targetType: A string indicating the type of entity associated with the event.

• text: A string field containing additional information or description related to the webhook event.

The fields targetCuid and targetCuids are mutually exclusive, meaning a payload will include either but never both.