Webhooks
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
Users should ensure the webhook feature is enabled in their PlexTrac account.
Users must confirm that the notification engine and notification service are running.
PlexTrac's webhook requests have a 5-second timeout. If an endpoint takes over five seconds to respond, the request will be retried up to five times with exponential backoff, potentially leading to duplicate events. To prevent this, ensure the endpoint reacts promptly.
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.
To retrieve a list of available webhook events, users should send a GET request to:
Users can create a new webhook by sending a POST request to:
The request should include a JSON body with the following parameters:
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:
Concatenate: Combine the secret with the raw JSON payload of the webhook request.
Hash: Generate an HMAC-SHA256 hash of the concatenated string.
Compare: Compare the generated hash with the value in the X-Authorization-HMAC-256 header. If they match, the webhook is authentic.
To get a list of existing webhooks, users can use this GET endpoint:
To modify an existing webhook, users should send a PATCH request to:
To test the webhook configuration, users can use this POST endpoint:
The request should include a JSON body like this:
To remove a webhook, users should send a DELETE request to:
To access webhook logs, users can use this GET endpoint:
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
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.
Using an HMAC-256 signature with PlexTrac webhooks is optional. If a secret is not provided, it will default to null, and no signature will be included. While not required, using a signature is highly recommended to enhance the security and authenticity of webhooks. for more information on verifying sender requests.