Webhooks

• Introduction

Webhooks provide a way for your application to receive real-time notifications about events that occur within our system. When a subscribed event is triggered—such as a report being created or a query being run—we will send an HTTP POST request to a URL you specify. This allows you to build powerful integrations, automate workflows, and keep your own systems synchronized with your data.

You can create and manage your webhooks directly from the application's user interface.

Events and Payloads

Report Related Events

This event is triggered when an entire report is executed, either on a schedule or manually. Crucially, the report.run event data will contain a query_result URL for each individual query that was part of the report.

report.created

{
  "event": "report.created",
  "report_id": 123,
  "report_name": "Quarterly User Growth",
  "report_description": "A detailed analysis of new user sign-ups and engagement for Q2.",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T18:30:00+00:00"
}

report.updated

{
  "event": "report.updated",
  "report_id": 123,
  "report_name": "Updated Quarterly User Growth",
  "report_description": "An updated analysis of new user sign-ups and engagement for Q2.",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T18:35:10+00:00"
}

report.deleted

{
  "event": "report.deleted",
  "report_id": 123,
  "report_name": "Updated Quarterly User Growth",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T18:40:25+00:00"
}

report.run

{
  "event": "report.run",
  "report_id": 1,
  "report_name": "Nam minus placeat nisi sint.",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "report_notebook_outputs": "http://laravel.test/api/reports/1/run/1",
  "queries": [
    {
      "query_id": 1,
      "query_name": "velit",
      "query_result": "http://laravel.test/api/reports/1/queries/1/reportRun/1"
    },
    {
      "query_id": 2,
      "query_name": "non",
      "query_result": "http://laravel.test/api/reports/1/queries/2/reportRun/1"
    },
    {
      "query_id": 3,
      "query_name": "alias",
      "query_result": "http://laravel.test/api/reports/1/queries/3/reportRun/1"
    }
  ],
  "timestamp": "2025-06-09T17:11:23+00:00"
}

Query Related Events

This event is more specific and is triggered only when actions are performed on an individual query in isolation.

• This includes running a query by itself or managing its specific schedule.
• Key Distinction: The query.run event will not be triggered if the query is run as part of a larger report execution. In that scenario, you should refer to the main report.run event to find the query's results.

query.created

{
  "event": "query.created",
  "query_id": 45,
  "query_name": "New User Signups by Region",
  "report_id": 123,
  "report_name": "Quarterly User Growth",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T19:05:15+00:00"
}

query.updated

{
  "event": "query.updated",
  "query_id": 45,
  "query_name": "Active Users by Region (Daily)",
  "report_id": 123,
  "report_name": "Quarterly User Growth",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T19:10:00+00:00"
}

query.deleted

{
  "event": "query.deleted",
  "query_id": 45,
  "report_id": 123,
  "report_name": "Quarterly User Growth",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "timestamp": "2025-06-09T19:15:40+00:00"
}

query.run

{
  "event": "query.run",
  "query_id": 3,
  "query_name": "alias",
  "report_id": 1,
  "report_name": "Nam minus placeat nisi sint.",
  "workspace_id": 1,
  "workspace_name": "Main Workspace",
  "query_result": "http://laravel.test/api/reports/1/queries/3/run/2",
  "timestamp": "2025-06-09T17:03:33+00:00"
}

Retrieving Run Results

The report.run and query.run event payloads provide URLs (report_notebook_outputs and query_result) instead of the actual run data. To download the results, you must make a GET request to the provided URL using your Personal API token for authentication.

Example cURL Request

Here is an example of how to fetch the results from a query.run event using curl.

curl -X POST "http://laravel.test/api/reports/1/queries/3/run/2" \
     -H "Authorization: Bearer YOUR_PERSONAL_API_TOKEN" \
     -H "Accept: application/json"