Webhooks are a real-time, event-driven communication method that allows PlexTrac to send data automatically when a specific event occurs. Using HTTP POST requests, webhooks enable immediate data transfer without constant polling, making them efficient and lightweight.

By providing a unique URL for event notifications, webhooks facilitate automation and real-time updates between applications while ensuring security through authentication methods and encryption.

Prerequisites

1. Users should ensure the webhook feature is enabled in their PlexTrac account.

2. Users must confirm that the notification engine and notification service are running.

Configuring Webhooks

The list below outlines the key operations of the webhook lifecycle, including retrieving available events, creating new webhooks, updating existing configurations, testing webhook functionality, deleting webhooks, and accessing logs.

Getting Available Events

To retrieve a list of available webhook events, users should send a GET request to:

text{{toplevel_domain}}/api/internal/webhookevents

Creating a Webhook

Users can create a new webhook by sending a POST request to:

text{{toplevel_domain}}/api/internal/webhooks

The request should include a JSON body with the following parameters:

json{
  "clientCuids": [],
  "name": "Your Webhook Name",
  "url": "https://your-webhook-url.com",
  "sslVerification": true,
  "events": ["ReportPublished"],
  "enabled": true,
  "secret": null
}

Webhook Security: HMAC-256 Signature Verification

To ensure the authenticity and integrity of webhooks, PlexTrac includes an HMAC-256 signature in the X-Authorization-HMAC-256 header of each webhook request. This signature is generated using the secret provided during the webhook's creation.

To verify the signature, follow these steps:

1. Concatenate: Combine the secret with the raw JSON payload of the webhook request.

2. Hash: Generate an HMAC-SHA256 hash of the concatenated string.

3. Compare: Compare the generated hash with the value in the X-Authorization-HMAC-256 header. If they match, the webhook is authentic.

Retrieving Webhooks

To get a list of existing webhooks, users can use this GET endpoint:

text{{toplevel_domain}}/api/internal/webhooks?page[size]=25&page[current]=1

Updating a Webhook

To modify an existing webhook, users should send a PATCH request to:

text{{toplevel_domain}}/api/internal/webhooks/{webhookCuid}

Testing a Webhook

To test the webhook configuration, users can use this POST endpoint:

text{{toplevel_domain}}/api/internal/webhooks/test

The request should include a JSON body like this:

json{
  "url": "https://your-test-webhook-url.com",
  "secret": "your_secret_key",
  "sslVerification": true
}

Deleting a Webhook

To remove a webhook, users should send a DELETE request to:

text{{toplevel_domain}}/api/internal/webhooks/{webhookCuid}

Viewing Webhook Logs

To access webhook logs, users can use this GET endpoint:

text{{toplevel_domain}}/api/internal/webhookslog?tenantCuid={tenantCuid}&limit=25&offset=0&webhookCuid={webhookCuid}

Validation Rules

When creating or updating webhooks, users must ensure that their requests adhere to the following validation rules:

• clientCuids: array of strings

• name: string

• url: string

• secret: string or null

• sslVerification: boolean

• events: array of strings (must include at least one valid event)

• enabled: boolean

Troubleshooting

• Users should monitor API logs for testWebhook events and their outcomes.

• After configuring a webhook, it is advisable to trigger an event (e.g., publishing a report) to verify its functionality.

• If users encounter a "Failed to call webhook" error, they should check their logs for more details.

• It is important to note that webhook requests must follow specific rules to prevent SSRF attacks. PlexTrac validates the IP address and protocol for security purposes.

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.

When events trigger a webhook, PlexTrac sends a POST request with the event payload to the configured URL. If a secret is provided during webhook setup, PlexTrac generates an HMAC-SHA256 signature using that secret and includes it in the x-authorization-hmac-256 header. Users can specify a secret when creating a webhook in the PlexTrac UI, enabling signature-based verification of incoming requests.

Generating the Signature

PlexTrac generates the signature using the following JavaScript code in the application:

const hmac = crypto.createHmac('SHA256', webhook.secret);
hmac.update(Buffer.from(JSON.stringify(payload)));
const signature = hmac.digest('hex');

Verifying the Signature in Python

To verify the signature in Python, follow these steps:

1. Extract the x-authorization-hmac-256 header from the incoming request.

2. Retrieve the webhook secret.

3. Convert the payload into a JSON string using json.dumps() with specific formatting to match JavaScript's JSON.stringify().

4. Compute the HMAC-SHA256 hash and compare it with the received signature using the secret.

Python Implementation (FastAPI Example):

import hmac
import hashlib
import json
from fastapi import Request

async def verify_webhook(request: Request, secret: str):
    # Extract the signature from the request headers
    hmac_header = request.headers.get("x-authorization-hmac-256")
    if not hmac_header:
        return False  # Missing signature header

    # Retrieve and format the JSON payload
    response_payload = await request.json()
    payload_str = json.dumps(response_payload, separators=(',', ':'))  # Match JSON.stringify()

    # Compute the HMAC-SHA256 hash
    hmac_obj = hmac.new(secret.encode(), payload_str.encode(), hashlib.sha256)
    sha256_hash = hmac_obj.hexdigest()
    
    # Compare the computed hash with the received signature
    return hmac_header == sha256_hash

Debugging Tips

If the generated hash does not match the received signature:

• Ensure that the JSON formatting is the same as JSON.stringify() (use separators=(',', ':')).

• Log the raw request body before parsing JSON to confirm the received data is correct:

raw_body = await request.body()
print(f"Raw Body: {raw_body.decode()}")

• Check for encoding mismatches when converting the JSON string.

• Confirm that both systems use the same secret for hashing.