1 of 1

Webhooks

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 who prefer a straightforward, visual approach to setting up webhooks should utilize the documentation page focused on integrations and webhooks through the application interface. This documentation is ideal for non-technical users or administrators who may not be familiar with API calls and prefer guided, step-by-step instructions.

Prerequisites

Users should ensure the webhook feature is enabled in their PlexTrac account.
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.

Get Available Events To retrieve a list of available webhook events, users should send a GET request to:
```
text{{toplevel_domain}}/api/internal/webhookevents
```

Create 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
}

Retrieve 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
```
Update a Webhook To modify an existing webhook, users should send a PATCH request to:
```
text{{toplevel_domain}}/api/internal/webhooks/{webhookCuid}
```

Test 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
}

Delete a Webhook To remove a webhook, users should send a DELETE request to:
```
text{{toplevel_domain}}/api/internal/webhooks/{webhookCuid}
```

View 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, triggering an event (e.g., publishing a report) is advisable 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.