Deliver Liveboard reports to an external application
26.4.0.cl
Cloud (Latest)

Deliver Liveboard reports to an external application

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🔗

ParameterDescription

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.

additional_headers
Optional

Array of key-value pairs. Allows including custom HTTP headers in every outbound webhook HTTP request that ThoughtSpot sends to the configured destination URL. When configured, ThoughtSpot sends these headers in addition to the authentication headers and standard HTTP headers such as Content-Type, User-Agent.

You can use this parameter to pass arbitrary headers with custom metadata in key-value pairs, as required by the webhook receiver endpoint:

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

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🔗

ParameterDescription

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.

To define a sorting criteria for the webhook records in API response, set the field_name to one of the following options:

  • CREATED
    Sorts the records by the webhook creation timestamp.

  • MODIFIED
    Sorts the webhook object by the last modified timestamp.

  • NAME
    Sorts the records alphabetically.

To specify the sort order, set order to ASC for ascending order, or DESC for descending order.

For example:

"sort_options": {
   "field_name":"CREATED",
   "order":"ASC"
}

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 '{
  "org_identifier": "testOrg1",
  "event_type": "LIVEBOARD_SCHEDULE"
}'

Example response🔗

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

{
   "webhooks":[
      {
         "id":"27997a8a-cd33-485d-a039-b40b71d191a8",
         "name":"webhook-lb-event",
         "description": "Webhook for Liveboard schedule",
         "org":{
            "id":"2100019165",
            "name":"testOrg1"
         },
         "url":"https://webhook-test-server-263n.onrender.com/",
         "url_params":null,
         "events":[
            "LIVEBOARD_SCHEDULE"
         ],
         "authentication":null,
         "signature_verification":null,
         "additional_headers":null,
         "creation_time_in_millis":1773824614455,
         "modification_time_in_millis":1773824614455,
         "created_by":{
            "id":"4e6e5692-667e-487d-9672-f301ccc2ea77",
            "name":"UserA@example.com"
         },
         "last_modified_by":null,
         "storage_destination":null
      }
   ],
   "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.

  • additional_headers
    Optional and custom HTTP headers in the webhook request triggered by ThoughtSpot.

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.

Verify the integration🔗

To verify the webhook configuration, send an API request to the /api/rest/2.0/system/communication-channels/validate API endpoint and check the connection status.

If the validation returns errors, verify the configuration and update the webhook properties.

If the connection status is successful, trigger a webhook delivery to the configured destination and verify the payload.

Monitor webhook delivery status🔗

To monitor the webhook delivery and job status, use the /api/rest/2.0/jobs/history/communication-channels/search API endpoint. For more information, see Monitor webhook delivery and job status.

Delete a webhook🔗

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

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,
      "additional_headers":null,
      "creation_time_in_millis": 1761184185887,
      "modification_time_in_millis": 1761184185887,
      "created_by": {
        "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b",
        "name": "UserA@example.com"
      },
      "last_modified_by": null,
      "storage_destination":null
    }
  ],
  "failed_webhooks": []
}

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.