Events and Webhooks

Developer

DataCentral can emit outbound webhooks when users interact with configured report visuals. This enables real-time integration with external systems — from CRM platforms to custom APIs — without requiring users to leave the DataCentral portal.

---

1. How Action Task Webhooks Work

When a Tenant Administrator configures an Action Task and binds it to a Power BI visual, DataCentral listens for user interactions on that visual (e.g., a click or a data point selection).

When the interaction is detected, DataCentral sends a POST request to the configured webhook URL. The payload contains two parts:

1. Metadata: Context about the event (who triggered it, from which report and visual).
2. Visual Data: The actual data values from the selected visual element.

Your webhook endpoint must respond with a 2xx HTTP status code to acknowledge receipt. DataCentral does not automatically retry failed webhook deliveries.

2. Webhook Payload Structure

Metadata Object

The metadata object is always included in the webhook payload and provides context about the triggering event.

{
  "actionTriggeredAt": "2026-02-01T12:30:42.000Z",
  "clientUrl": "https://yourtenant.datacentral.ai",
  "currentUser": 522,
  "reportId": "07ab3fe6-8fbb-4f42-834b-62290e0e0cef1",
  "reportName": "Sales Overview",
  "tenancyName": "yourtenant",
  "visualName": "4b09962ae566a8566606"
}

Field	Type	Description
actionTriggeredAt	string (ISO 8601)	The UTC timestamp when the user triggered the action.
clientUrl	string	The base URL of the DataCentral Tenant where the action was triggered.
currentUser	integer	The internal DataCentral User ID of the user who triggered the action.
reportId	string (GUID)	The DataCentral Item ID of the report.
reportName	string	The display name of the report.
tenancyName	string	The subdomain name of the Tenant.
visualName	string	The internal Power BI visual ID that was interacted with.

Visual Data Array

The visual data array contains the data context from the selected element in the Power BI visual. This is the core payload your integration will use to take action.

[
  {
    "visual": "4b09962ae566a8566606",
    "data": [
      {
        "identity": [
          {
            "equals": "Anna Appleseed",
            "target": {
              "table": "d_employee",
              "column": "fullname"
            }
          }
        ],
        "values": [
          {
            "value": 199,
            "formattedValue": "199.0",
            "target": {
              "$schema": "http://powerbi.com/product/schema#columnAggr",
              "aggregationFunction": "Sum",
              "table": "v_timesheet",
              "column": "duration_hours"
            }
          }
        ]
      }
    ]
  }
]

The identity array describes the row identity (the "who" or "what" was selected), and the values array contains the associated measures (the "how much" or "how many").

3. Securing Your Webhook Endpoint

Your webhook endpoint is publicly accessible, so you must secure it to prevent unauthorized calls.

• Use a Secret Token: When configuring an Action Task in DataCentral, you can specify a secret token that DataCentral will include in the Authorization header of every webhook request. Your endpoint should validate this token before processing the payload.
• HTTPS Only: Always use an HTTPS endpoint. Never accept webhook payloads over plain HTTP.
• IP Allowlisting: If your infrastructure supports it, allowlist the IP addresses of your DataCentral instance to reject requests from unknown sources.

4. Accessing Audit Logs via API

In addition to outbound webhooks, DataCentral provides an API endpoint to query the administrative audit log programmatically.

Endpoint: GET /v1/audit-logs

This endpoint returns a paginated list of administrative events. You can filter the results using the following query parameters:

Parameter	Type	Description
userId	integer	Filter events by a specific user's internal ID.
actionType	string	Filter by event type (e.g., UserCreated, RoleUpdated, ReportExported).
dateRange	string	Filter by a date range in ISO 8601 format (e.g., 2026-01-01/2026-01-31).
page	integer	The page number for pagination.
pageSize	integer	The number of results per page (default: 50, max: 200).