Webhooks for KPI monitor alerts

Table of Contents

Before you begin
Configure Webhooks
- Register a Webhook
- Assign Webhook to a KPI Monitor alert
Webhook schema
Additional references

ThoughtSpot users with administrator or developer privileges can register a Webhook to send Monitor alerts from a Key Performance Indicator (KPI) chart to an external application. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user.

For example, you can create an alert to be notified when a Sales KPI exceeds a threshold of 200,000, or when your weekly sales increase by 2%. By default, the email notifications are sent to the alert subscriber’s email address. With Webhooks, you can trigger alerts to the REST endpoint of an external application via HTTP POST requests and customize your application workflow to present these alerts as SMS messages or Slack notifications.

Before you begin🔗

Make sure your ThoughtSpot user account has the privileges required to access the Develop page in the ThoughtSpot UI.
Your destination application has a callback URL to accept HTTP POST requests.
If you plan to use OAuth authentication, make sure you have the OAuth credentials and authorization URL of your application
If you plan to use an API key for authentication, ensure that you have a valid API key.

Configure Webhooks🔗

To configure a Webhook and send alert data to the destination URL, complete the following steps:

Register a Webhook🔗

To register a Webhook in ThoughtSpot, complete the following steps:

Go to Develop > Customizations > Webhooks.

If you are using the new experience, the Developer will be in the Application switcher .
Click Create Webhook.
In the Create Webhook modal, specify the Webhook name and the URL of the destination application.

For testing purposes, you can use a URL from the Webhook site.
Specify the authentication type.
- No authentication
  Default authentication option. Not recommended for production environments.
- API Key
  Allows using an API key to authenticate API requests to the destination URL. Specify the API key to use in the X-API-Key request header.
- OAuthentication 2.0
  Allows using OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. If the registered Webhook has Oauth authentication enabled, Authorization: Bearer <access-token> is sent in the request header.
If the destination URL requires query parameters to be passed in the request URL, specify the parameters as key-value pairs.
Click Save.

Assign Webhook to a KPI Monitor alert🔗

To assign the registered Webhook to an alert:

Go to a KPI chart and click the Create alert icon.
If the alert is already configured, go to Monitor and click Edit alert to modify the alert properties.
In the alert configuration modal, go to Select notification channel and select Custom channel and the Webhook.
Ensure that alert type and subscription details are defined.
Click Save.
Based on the type of alert, the notification payload will be sent in JSON format to the Webhook URL via HTTP POST request.

The following example shows the notification payload:

{
  "data": {
    "currentUser": {
      "displayName": "Guest 1",
      "email": "[email protected]"
    },
    "schemaVersion": "v1",
    "schemaType": "MONITOR",
    "notificationType": "UPDATION",
    "updationWebhookNotification": {
      "modifyUrl": "",
      "monitorRuleForWebhook": {
        "scheduleString": "hourly every hour ",
        "metricName": "Total Revenue Trend",
        "alertType": "Scheduled",
        "metricId": {
          "pinboardVizId": {
            "pinboardId": "22a8f618-0b4f-4401-92db-ba029ee13486",
            "vizId": "ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb"
          }
        },
        "metricUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb",
        "ruleName": "Alert on Total Revenue Trend",
        "conditionString": "",
        "ruleId": "a4b0a1f4-279d-42ab-a710-4ba6964869fa"
      },
      "unsubscribeUrl": "http://{ThoughtSpot-Host}/?utm_source=kpi_monitor&utm_medium=webhook/#/pinboard/22a8f618-0b4f-4401-92db-ba029ee13486/ce4dc8ca-e4f9-4fd4-b562-2bb9e69fd0cb?ts-type=unsubscribeFromRule&ts-ruleid=a4b0a1f4-279d-42ab-a710-4ba6964869fa"
    }
  }
}

Webhook schema🔗

The following Webhook schema is used when sending an HTTP POST request body to the registered Webhook URL:

WebhookNotification {
    enum SchemaVersion,
    enum EventSchemaType,
    enum NotificationType,
    User CurrentUser,
    DeletionWebhookNotification deletionWebhookNotification,
    FailureWebhookNotification failureWebhookNotification,
    ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification,
    SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification,
    SubscriptionWebhookNotification subscriptionWebhookNotification,
    ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification,
    UpdationWebhookNotification updationWebhookNotification,
}

The fields are populated according to the notification type. For all types of notifications, the following four fields are populated:

SchemaVersion
The version of the schema used
```
enum SchemaVersion {
	v1,
}
```
EventSchemaType
Type of the schema used
```
enum EventSchemaType {
	MONITOR,
}
```

NotificationType
Type of the monitor notification sent

enum NotificationType {
    SELF_SUBSCRIPTION,
    DELETION,
    UPDATION,
    FAILURE,
    SUBSCRIPTION,
    SCHEDULE_METRIC_UPDATE,
    THRESHOLD_METRIC_UPDATE,
}

CurrentUser
User for which the notification is sent.

User {
    String id,
    String displayName,
    String email,
}

Conditional fields include:

DeletionWebhookNotification deletionWebhookNotification
Populated only when notificationType is DELETION.
FailureWebhookNotification failureWebhookNotification
Populated only when notificationType is FAILURE.
ScheduledMetricUpdateWebhookNotification scheduledMetricUpdateWebhookNotification,
Populated only when notificationType is SCHEDULE_METRIC_UPDATE.
SelfSubscriptionWebhookNotification selfSubscriptionWebhookNotification,
Populated only when notificationType is SELF_SUBSCRIPTION.
SubscriptionWebhookNotification subscriptionWebhookNotification,
Populated only when notificationType is SUBSCRIPTION.
ThresholdReachedMetricUpdateWebhookNotification thresholdReachedMetricUpdateWebhookNotification,
Populated only when notificationType is THRESHOLD_METRIC_UPDATE.
UpdationWebhookNotification updationWebhookNotification
Populated only when notificationType is UPDATION.

The following examples show the schema for different alert notification types:

Scheduled alert notification🔗

A scheduled alert is sent as per the configured periodicity.

The following schema is used in the notification sent for scheduled alerts:

ScheduledMetricUpdateWebhookNotification {
    MonitorRuleForWebhook monitorRuleForWebhook,
    String modifyUrl,
    String unsubscribeUrl,
    RuleExecutionDetails ruleExecutionDetails,
}

The following example shows the email notification for a scheduled alert:

Threshold alert notification🔗

A threshold alert is sent when a metric in the KPI chart reaches the configured threshold.

The following schema is used in the notification sent for threshold alerts:

ThresholdReachedMetricUpdateWebhookNotification {
    MonitorRuleForWebhook monitorRuleForWebhook,
    String modifyUrl,
    String unsubscribeUrl,
    RuleExecutionDetails ruleExecutionDetails,
}

The following example shows the email notification for a threshold alert:

SelfSubscription notification🔗

A self-subscription notification is sent for alerts self-subscribed by a user.

The following schema is used in the notification sent for self-subscribed notifications:

SelfSubscriptionWebhookNotification {
    MonitorRuleForWebhook monitorRuleForWebhook,
    String modifyUrl,
    String unsubscribeUrl,
    RuleExecutionDetails ruleExecutionDetails,
}

The following example shows the email notification sent for a self-subscribed alert:

Subscription notifications🔗

A subscription notification is sent when a user subscribes to a notification.

The following schema is used in the subscription notification:

SubscriptionWebhookNotification {
    MonitorRuleForWebhook monitorRuleForWebhook,
    String modifyUrl,
    String unsubscribeUrl,
    RuleExecutionDetails ruleExecutionDetails,
    User subscribedByUser,
}

The following example shows the email notification sent from ThoughSpot after a user subscribes to an alert:

Delete Webhook notification🔗

A delete notification is sent to subscribers when an alert they subscribed to is deleted in ThoughtSpot.

The following schema is used in the notification sent when an alert is deleted:

DeletionWebhookNotification {
	String ruleName,
	String metricName,
	MetricId metricId,
	User deletedByUser,
}

The following example shows the email notification sent to the subscribers when an alert is deleted:

Failure Webhook notification🔗

A failure notification is sent to subscribers when an alert execution fails.

The following schema is used in the notification sent when a Webhook alert fails:

FailureWebhookNotification {
    MonitorRuleForWebhook monitorRuleForWebhook,
    String modifyUrl,
    String unsubscribeUrl,
    String reason,
}

The following example shows the email notification sent to the subscribers when an alert execution fails: