Deliver Liveboard reports to an external application using a webhook

^Beta

By configuring a webhook, users can send notifications automatically to a target application whenever a scheduled Liveboard job is triggered in ThoughtSpot.

Note

Webhook support for Liveboard schedule events is available only on ThoughtSpot Cloud instances with 10.14.0.cl or later. The webhook feature is currently in beta and not enabled by default. To enable this feature on your instance, contact ThoughtSpot Support.
You can configure only one webhook for the Liveboard schedule event per Org.

Overview🔗

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.

Configure a webhook for the Liveboard schedule event to enable programmatic communication between the target application and ThoughtSpot.
To create and manage webhook APIs, use the following APIs:
- POST /api/rest/2.0/webhooks/create
- POST /api/rest/2.0/webhooks/delete
- POST /api/rest/2.0/webhooks/search
- POST /api/rest/2.0/webhooks/{webhook_identifier}/update

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.

Configuration steps🔗

The webhook setup for Liveboard schedule events includes the following steps:

Configure a webhook🔗

To configure webhooks for the Liveboard schedule event, use the webhook REST API.

Create a webhook🔗

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`	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 the event as `LIVEBOARD_SCHEDULE`.
`authentication`	Defines authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint. Specify the authentication type. `API_KEY` API key to authorize the payload requests. Specify the API key to use in the `X-API-Key` request header. `BASIC_AUTH` Authentication methods with username and password. `BEARER_TOKEN` Authentication token to authenticate and 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. This typically involves ThoughtSpot signing the webhook payload with a secret, and your webhook endpoint validating this signature using the shared secret. If using signature verification, specify the following parameters. `type` Signature verification type. Supported type is `HMAC_SHA256`, which uses Hash-based Message Authentication Code (HMAC) algorithm with the SHA-256 hash function to generate a cryptographic signature for webhook payloads. When configured, ThoughtSpot will sign the webhook payload using a shared secret and the HMAC_SHA256 algorithm. Your receiving endpoint should use the same secret and algorithm to compute the HMAC of the received payload and compare it to the signature sent by ThoughtSpot. `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 S3 storage destination. For more information, see Deliver content to AWS S3 storage using webhooks.

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

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 the event as LIVEBOARD_SCHEDULE.

authentication

Defines authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint.

Specify the authentication type.

API_KEY
API key to authorize the payload requests. Specify the API key to use in the X-API-Key request header.
BASIC_AUTH
Authentication methods with username and password.
BEARER_TOKEN
Authentication token to authenticate and 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. This typically involves ThoughtSpot signing the webhook payload with a secret, and your webhook endpoint validating this signature using the shared secret.

If using signature verification, specify the following parameters.

type
Signature verification type. Supported type is HMAC_SHA256, which uses Hash-based Message Authentication Code (HMAC) algorithm with the SHA-256 hash function to generate a cryptographic signature for webhook payloads. When configured, ThoughtSpot will sign the webhook payload using a shared secret and the HMAC_SHA256 algorithm. Your receiving endpoint should use the same secret and algorithm to compute the HMAC of the received payload and compare it to the signature sent by ThoughtSpot.
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 S3 storage destination. For more information, see Deliver content to AWS S3 storage using webhooks.

Example request🔗

The following example shows the request body for creating a webhook:

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.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d",
  "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 204 response code.

View webhook properties🔗

To view the properties of a webhook or get a list of webhooks configured on your ThoughtSpot instance, send a POST request to the /api/rest/2.0/webhooks/search API endpoint.

To get specific information, define the following parameters. If the API request is sent without parameters in the request body, ThoughtSpot returns the webhooks configured for the Org context in ThoughtSpot.

Request parameters🔗

Parameter Description

Parameter	Description
`org_identifier` Optional	String. ID or name of the Org.
`webhook_identifier` Optional	String. ID or name of the webhook.
`event_type` Optional	String. Type of webhook event to filter by. For Liveboard schedule events, specify `LIVEBOARD_SCHEDULE`.
Pagination settings	If fetching multiple records, specify the following parameters to paginate the API response: `record_offset` Integer. Specifies the starting point (index) from which records should be returned. Default is 0. `record_size` Integer. Specifies the number of records to return in the response. Default is 50.
`sort_options` Optional	Enables sorting of the API response by a specific field in ascending or descending order. Specify the `field_name` and define the desired sort order.

org_identifier
Optional

String. ID or name of the Org.

webhook_identifier
Optional

String. ID or name of the webhook.

event_type
Optional

String. Type of webhook event to filter by. For Liveboard schedule events, specify LIVEBOARD_SCHEDULE.

Pagination settings

If fetching multiple records, specify the following parameters to paginate the API response:

record_offset
Integer. Specifies the starting point (index) from which records should be returned. Default is 0.
record_size
Integer. Specifies the number of records to return in the response. Default is 50.

sort_options
Optional

Enables sorting of the API response by a specific field in ascending or descending order. Specify the field_name and define the desired sort order.

Example request🔗

The following example shows the request body to fetch webhook properties:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "record_offset": 0,
  "record_size": 50,
  "org_identifier": "testOrg1",
  "event_type": "LIVEBOARD_SCHEDULE"
}'

Example response🔗

If the API request is successful, ThoughtSpot returns the webhook configuration details:

{
  "webhooks": [
    {
      "id": "873dd4e2-6493-490d-a649-ba9ea66b11f5",
      "name": "webhook-lb-event",
      "description": "Webhook for Liveboard schedule",
      "org": {
        "id": "2100019165",
        "name": "testOrg1"
      },
      "url": "https://webhook.site/view/6643eba5-9d3e-42a1-85e0-bb686ba1524d/29c02fc2-c1c6-4b20-8d62-e8d51cf8dfb3",
      "url_params": null,
      "events": [
        "LIVEBOARD_SCHEDULE"
      ],
      "authentication": null,
      "signature_verification": null,
      "creation_time_in_millis": 1761050197164,
      "modification_time_in_millis": 1761051944507,
      "created_by": {
        "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b",
        "name": "UserA@UserA@example.com"
      },
      "last_modified_by": {
        "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b",
        "name": "UserA@UserA@example.com"
      }
    }
  ],
  "pagination": {
    "record_offset": 0,
    "record_size": 50,
    "total_count": 1,
    "has_more": false
  }
}

Update the properties of a webhook🔗

To update the name, description text, endpoint URL, or the authentication settings of a webhook object, send a POST request to the /api/rest/2.0/webhooks/{webhook_identifier}/update API endpoint.

Request parameters🔗

Specify the webhook_identifier and pass it as a path parameter in the request URL.

The API operation allows you to update the following webhook properties:

name
Name of the webhook.
description
Description text of the webhook.
url
The URL of the webhook endpoint.
url_params
Query parameters to append to the endpoint URL.
events
Events subscribed to the webhook. In the current release, ThoughtSpot supports only the LIVEBOARD_SCHEDULE event.
authentication
Authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint.
signature_verification
Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests.

Example request🔗

The following example shows the request body for updating the name, description text, and endpoint URL of a webhook object:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/webhook-lb-test/update'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "name": "webhook-lb-event",
  "description": "Webhook for Liveboard schedule event",
  "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f",
  "events": [
    "LIVEBOARD_SCHEDULE"
  ]
}'

Example response🔗

If the API request is successful, the API returns a 204 response code indicating a successful operation.

Delete a webhook🔗

To delete a webhook, send a POST request to the /api/rest/2.0/webhooks/delete endpoint.

Note	When you delete a webhook with S3 storage, the webhook endpoint is removed and any events or workflows configured to use that webhook can no longer deliver payloads. Files already stored in S3 are not deleted as part of webhook deletion; only the delivery mechanism is removed.

Request parameters🔗

Specify the name or ID of the webhook to delete.

Parameter Description

Parameter	Description
`webhook_identifiers`	Array of strings. ID or name of the webhooks to delete.

webhook_identifiers

Array of strings. ID or name of the webhooks to delete.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/delete'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "webhook_identifiers": [
    "webhook-lb-test"
  ]
}'

Example response🔗

If the API request is successful, the webhook is deleted, and the API returns the details of the deleted webhook in the response body.

{
  "deleted_count": 1,
  "failed_count": 0,
  "deleted_webhooks": [
    {
      "id": "45fe7810-3239-4761-94fd-04c017df29c4",
      "name": "webhook-test",
      "description": "Webhook for testing purposes",
      "org": {
        "id": "1574427524",
        "name": "testOrg2025"
      },
      "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f",
      "url_params": null,
      "events": [
        "LIVEBOARD_SCHEDULE"
      ],
      "authentication": null,
      "signature_verification": null,
      "creation_time_in_millis": 1761184185887,
      "modification_time_in_millis": 1761184185887,
      "created_by": {
        "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b",
        "name": "UserA@UserA@example.com"
      },
      "last_modified_by": null
    }
  ],
  "failed_webhooks": []
}

Verify the integration🔗

To verify the integration, trigger a webhook delivery and verify the payload.

For testing purposes, you can use a URL from Webhook.site as a webhook endpoint and check the payload when the Liveboard schedule event is triggered.

Contents of the webhook payload🔗

See Webhook payload.

Deliver Liveboard reports to an external application using a webhook

Overview🔗

Before you begin🔗

Configuration steps🔗

Configure a webhook🔗

Create a webhook🔗

Request parameters🔗

Example request🔗

Example response🔗

View webhook properties🔗

Request parameters🔗

Example request🔗

Example response🔗

Update the properties of a webhook🔗

Request parameters🔗

Example request🔗

Example response🔗

Delete a webhook🔗

Request parameters🔗

Example request🔗

Example response🔗

Verify the integration🔗

Contents of the webhook payload🔗

Additional resources🔗