Skip to main content
Version: I2023.4.1

Engine Webhooks

Webhooks can be configured for engine-level events.

To select an engine-level Webhooks event, select Settings > Webhooks from the left-hand menu under Organization Settings. Then select Event to reveal the drop-down menu with all engine-related webhook events.

Figure 1. The Webhooks button under Organization Settings

image

Figure 2. The engine webhook for Aggregate Batch Start

image

You can configure engine-level webhooks for the following events from the Event drop-down menu:

  • Aggregate Batch Start
  • Aggregate Batch Success/Failure
  • Aggregate Prune Result
  • Schema Publish
  • Slow Query
  • Slow Agg Builds
  • Project Unpublish

For details, see the sections below.

Common parameters​

The following POST parameters are used for most of the webhooks:

  • id - UUID of the batch
  • org_id - UUID of the organization
  • project_id - UUID of the project
  • cube_id - UUID of the cube; if not available, the value in the payload is 'null'
  • event_type - unique value for each event type

Event: Aggregate Batch Start​

Purpose of webhook: To send a callback upon the initiation of a process to build instances of the aggregate tables for a published cube.

POST parameters:

  • Common parameters: id, org_id, project_id, cube_id
  • is_full_build - The value true indicates that all aggregate instances are being fully build. The value false indicates that aggregate instances are being built incrementally.
  • event_type - For this event type, the value is aggregate_batch_started.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request:

{
 "event_type" : "aggregate_batch_started",
 "id" : "378f70a0-9d1f-4591-b64f-89008b079075",
 "context" : {
   "org_id" : "default",
   "project_id" : "91db9aa1-8947-4e7a-b613-af2ea485990d"
 },
 "is_full_build" : false,
 "cube_id" : "48d6ad30-f139-4f77-517f-36158d7b032b"
}

Event: Aggregate Batch Success/Failure​

Purpose of webhook: To send a callback when the build process for the aggregate tables of a published cube ends.

POST parameters:

  • Common parameters: id, org_id, project_id, cube_id
  • error - If the build process failed, this parameter gives a description of the error. If the build process is successful, the value of this parameter is null.
  • event_type - For this event type, the value is aggregate_batch_result.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request:

{
 "event_type" : "aggregate_batch_result",
 "id" : "378f70a0-9d1f-4591-b64f-89008b079075",
 "context" : {
   "org_id" : "default",
   "project_id" : "91db9aa1-8947-4e7a-b613-af2ea485990d"
 },
 "error" : null,
 "cube_id" : "48d6ad30-f139-4f77-517f-36158d7b032b"
}

Aggregate Prune Result​

Purpose of webhook: To send a callback when the Cubes in a published project are exceeding their configured limits on the number of active aggregates.

POST parameters:

  • Common parameters: id, org_id, project_id, cube_id
  • event_type - For this event type, the value is aggregate_prune_result.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request:

{
 "event_type" : "aggregate_prune_result",
 "id" : "378f70a0-9d1f-4591-b64f-89008b079075",
 "context" : {
   "org_id" : "default",
   "project_id" : "91db9aa1-8947-4e7a-b613-af2ea485990d"
 },
 "cube_id" : "48d6ad30-f139-4f77-517f-36158d7b032b"
}

Event: Schema Publish​

Purpose of webhook: To send a callback when a project is created by the pasting or uploading of a project.xml or JSON file on the New Project page of the Design Center.

POST parameters:

  • Common parameters: org_id, project_id
  • schema_id - UUID of the project.
  • status - Indicates whether the creation of the project succeeded or failed. The values are success and failure.
  • event_type - For this event type, the value is publish_schema_response.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request:

{
 "event_type": "publish_schema_response",
 "callback_url": "http://localhost:10502/webhooks/debug/test-callback",
 "created_by_user": "vpareto"
}

Event: Slow Query​

Purpose of webhook: To send a callback when the runtime of the queries meet or exceed a user defined cutoff threshold. A slow query execution is four seconds or more by default.

POST parameters:

  • Common parameters: org_id, project_id, cube_id
  • query_success - T/F flag for whether or not the query was successful.
  • query_id - The UUID of the query.
  • time_taken - The total time the query ran.
  • finished_at - The datetimestamp of when the query completed.
  • event_type - For this event type, the value is slow_query_event.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request

{
 "event_type" : "slow_query_event",
 "query_id" : "04dd09c8-4cfd-47b6-9dba-caf970880d6e",
 "finished_at" : "2021-12-07T15:44:07.077397Z",
 "org_id" : "default",
 "query_success" : true,
 "time_taken" : 3.7080559730529785,
 "project_id" : "91db9aa1-8947-4e7a-b613-af2ea485990d",
 "cube_id" : "48d6ad30-f139-4f77-517f-36158d7b032b"
}

Event: Slow Agg Builds​

Purpose of webhook: To send a callback when a slow aggregate build occurs, including successful, running, and failed builds. A slow aggregate build is four seconds or more by default.

POST parameters:

  • Common parameters: org_id, project_id, cube_id
  • type - The type of slow aggregate build event. For example, aggregate-build-completed-event.
  • instance_id - The UUID of the aggregate instance.
  • definition_id - The UUID of the aggregate definition.
  • triggering_query_id - The UUID of the query that triggered the aggregate build.
  • user_defined_id - The UUID of the aggregate, if it is a user-defined aggregate.
  • user_defined_name - The name of the aggregate, if it is a user-defined aggregate.
  • message - An optional message associated with the aggregate.
  • status - Indicates the current status of the event. For example, done.
  • duration - The duration of the event, in milliseconds.
  • event_type - For this event type, the value is slow_agg_builds.

Example URL for a POST request:

http://ATSCALE_ENGINE_HOST:10502/webhooks/orgId/default/envId/prod

Example payload in POST request:

{
 "type" : "aggregate-build-completed-event",
 "status" : "done",
 "duration" : 7623,
 "instance_id" : "b4a8bc98-ea83-4167-8dd4-7f6e8eb0e439",
 "definition_id" : "f314e8da-2d54-4297-93e7-aa5b957751e4",
 "triggering_query_id" : "8958cebf-8350-4fff-8347-ecec4b06ac88",
 "org_id" : "default",
 "project_id" : "91db9aa1-8947-4e7a-b613-af2ea485990d",
 "event_type" : "slow_agg_builds",
 "cube_id" : "48d6ad30-f139-4f77-517f-36158d7b032b"
}

Event: Project Unpublish​

Purpose of webhook: To send a callback when a project is unpublished from the Engine.

POST parameters: None.

Example URL for a POST request:

http://MY_WEBHOOK_RECEIVER_HOST/atscale/unpublish-schema

Example payload in POST request:

{
  "event_type" : "unpublish_schema_success",
   "context" : {
    "org_id" : "default",
    "project_id" : "161d6ee9-7548-4004-46e7-89b15d70cd5b"
  }
}

More information​

Example Code for a Webhook Receiver Server