Webhook configuration for Liveboard scheduled events

Table of Contents

Before you begin
Configuring a webhook

If you have scheduled a Liveboard job to receive a daily report via email, you can configure ThoughtSpot to send the report directly to a webhook endpoint and create your own custom emails or workflows.

Before you begin🔗

Check your application environment for the following prerequisites:

Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs.
If your instance has Role-based Access Control (RBAC) enabled, you need the following privileges:
- APPLICATION_ADMINISTRATION (Can Manage Application settings) to create and view communication channels.
- CAN_MANAGE_WEBHOOKS (Can manage webhooks) to create and manage webhooks.
Ensure that a webhook communication channel is configured for your Org or at the cluster level on your instance.
Ensure that your destination application has a callback URL to accept HTTP POST requests from ThoughtSpot.
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.

Configuring a webhook🔗

You can configure a webhook to deliver reports generated from Liveboard scheduled events to external applications. To create and manage webhooks, use the webhook REST API or the Webhooks page (new experience) in the UI.

Using Webhooks REST API🔗

To create a webhook for the Liveboard schedule event, send a POST request to the /api/rest/2.0/webhooks/create API endpoint. ThoughtSpot allows only one webhook per Org.

Request parameters🔗

Parameter Description

Parameter	Description
`name`	String. Name of the webhook.
`description` Optional	String. Description text for the webhook.
`url`	String. The fully qualified URL of the listening endpoint to which you want to send webhook notifications.
`url_params`	Optional. A JSON map of key-value pairs to append as query parameters in the webhook URL.
`events`	Array of strings. List of events to subscribe to. Specify `LIVEBOARD_SCHEDULE`.
`authentication`	Defines the authentication method and credentials ThoughtSpot uses when sending HTTP requests to the webhook endpoint. Specify the authentication type: `API_KEY` API key header and its value. `BASIC_AUTH` Username and password to authorize requests. `BEARER_TOKEN` Authentication token to authorize requests. `OAUTH2` 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.
`signature_verification` Optional	Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. ThoughtSpot signs the webhook payload with a secret, and your webhook endpoint validates the signature using the shared secret. If using signature verification, specify the following parameters: `type` Signature verification type. The supported type is `HMAC_SHA256`. `header` HTTP header where the signature is sent. `algorithm` Hash algorithm used for signature verification. `secret` Shared secret used for HMAC signature generation.
`storage_destination` Optional	Configuration parameters for the cloud storage destination. ThoughtSpot supports AWS S3 and GCP GCS as storage destinations. For more information, see Deliver Liveboard reports to AWS S3 storage and Deliver Liveboard reports to GCS storage.
`status` Optional	String. Status of the webhook. Specify `ENABLED` to activate the webhook immediately after creation, or `DISABLED` to create it in a deactivated state.
`additional_headers` Optional	Array of key-value pairs. Custom HTTP headers to include in every outbound webhook request, in addition to authentication headers and standard HTTP headers such as `Content-Type` and `User-Agent`. `"additional_headers": [ { "key":"X-Custom-Header", "value":"custom_value" } ]`

name

String. Name of the webhook.

description
Optional

String. Description text for the webhook.

url

String. The fully qualified URL of the listening endpoint to which you want to send webhook notifications.

url_params

Optional. A JSON map of key-value pairs to append as query parameters in the webhook URL.

events

Array of strings. List of events to subscribe to. Specify LIVEBOARD_SCHEDULE.

authentication

Defines the authentication method and credentials ThoughtSpot uses when sending HTTP requests to the webhook endpoint.

Specify the authentication type:

API_KEY
API key header and its value.
BASIC_AUTH
Username and password to authorize requests.
BEARER_TOKEN
Authentication token to authorize requests.
OAUTH2
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.

signature_verification
Optional

Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. ThoughtSpot signs the webhook payload with a secret, and your webhook endpoint validates the signature using the shared secret.

If using signature verification, specify the following parameters:

type
Signature verification type. The supported type is HMAC_SHA256.
header
HTTP header where the signature is sent.
algorithm
Hash algorithm used for signature verification.
secret
Shared secret used for HMAC signature generation.

storage_destination
Optional

Configuration parameters for the cloud storage destination. ThoughtSpot supports AWS S3 and GCP GCS as storage destinations. For more information, see Deliver Liveboard reports to AWS S3 storage and Deliver Liveboard reports to GCS storage.

status
Optional

String. Status of the webhook. Specify ENABLED to activate the webhook immediately after creation, or DISABLED to create it in a deactivated state.

additional_headers
Optional

Array of key-value pairs. Custom HTTP headers to include in every outbound webhook request, in addition to authentication headers and standard HTTP headers such as Content-Type and User-Agent.

"additional_headers": [
   {
      "key":"X-Custom-Header",
      "value":"custom_value"
   }
]

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "name": "webhook-lb-event",
  "url": "https://webhook-destination-site.com",
  "events": [
    "LIVEBOARD_SCHEDULE"
  ],
  "authentication": {
    "BEARER_TOKEN": "Bearer {AUTH_TOKEN}"
  },
  "description": "Webhook for Liveboard schedule"
}'

Example response🔗

If webhook creation is successful, the API returns a response body with the webhook details:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "My Liveboard Webhook",
  "description": "Webhook to notify external system about liveboard schedules",
  "org": {
    "id": "0",
    "name": "Primary"
  },
  "url": "https://webhook-destination-site.com",
  "events": [
    "LIVEBOARD_SCHEDULE"
  ],
  "authentication": {
    "BEARER_TOKEN": "***"
  },
  "creation_time_in_millis": 1724277430243,
  "modification_time_in_millis": 1724277430243,
  "additional_headers": [
    {
      "key": "Custom-Header",
      "value": "value1"
    },
    {
      "key": "Custom-Header-2",
      "value": "value2"
    }
  ],
  "created_by": {
    "id": "8e3f2a7b-9c4d-4e5f-8a1b-7c9d3e6f4a2b",
    "name": "UserA"
  },
  "last_modified_by": {
    "id": "8e3f2a7b-9c4d-4e5f-8a1b-7c9d3e6f4a2b",
    "name": "UserA"
  }
}

Through the Webhooks page in UI🔗

If the new Webhooks page is enabled on your instance, you can create a webhook via the UI.

Creating a webhook🔗

To add a webhook for the Liveboard schedule events:

Go to Develop > Customizations and click Webhooks.
In the Webhooks page, click Create webhook.
In the Create webhook modal, configure the following:
- Name: A display name for the webhook.
- URL: The fully qualified HTTPS URL of the endpoint that will receive webhook payloads.
- Description: (optional) A short description of the webhook’s purpose.
- Event type: Specify the ThoughtSpot event types to subscribe to. Ensure that Liveboard schedule is set as the event type.
Configure the authentication method your destination endpoint requires.
ThoughtSpot sends the configured credentials in every outbound request. The following options are available:
- No Authentication: No authentication headers are added to the request. Not recommended for production use.
- OAuth 2.0: Specify the OAuth client ID, client secret, and authorization URL.
- API Key: Specify the header or query parameter name for the API key and its value.
- Bearer Token: ThoughtSpot sends a static bearer token in the Authorization: Bearer header.
- Basic authentication: Username and password to authorize delivery requests.
Configure the file storage options. For more information, see AWS S3 storage integration for webhook delivery and GCS storage integration for webhook delivery.
Configure the advanced settings if required:
- Signature verification
  Specify the signature to send in the header for your endpoint to verify each request. Configure HMAC-SHA256 payload signing. ThoughtSpot signs each outbound payload with a shared secret. Your endpoint can use the same secret and algorithm to verify the signature in the incoming request header.
- Custom headers
  Use this feature to pass arbitrary metadata required by your endpoint in addition to standard and authentication headers. Define key-value pairs of custom headers to add to every outbound HTTP request.
- URL parameters: Specify the query parameters to append to the webhook URL on every request.
Click Save.
If the webhook is created successfully, it is added to the Webhooks list and enabled by default.

Test webhook connection and verify delivery🔗

To validate the webhook channel configuration, use one of the following options:

Use the /api/rest/2.0/system/communication-channels/validate API endpoint.
If the new Webhooks page is enabled on your instance, navigate to the Webhooks page, select the webhook row, and click Send test event.
1. Verify the delivery status.
2. If files are delivered to the configured URL endpoint, check the payload contents. For information about the webhook payload structure, see Webhook payload for Liveboard events.
3. If files are not delivered to the configured URL endpoint, check the logs for errors.