Configure, validate and monitor communication channels
26.4.0.cl
Cloud (Latest)

Configure, validate and monitor communication channels

Beta

To provide flexibility and programmatic control for ThoughtSpot administrators and developers who want to customize notifications and automate workflows based on Liveboard scheduling events, use the webhook communication channel.

This document describes the steps to configure communication channel preferences, validate configuration, and monitor the health and status of communication channels using REST APIs.

Note

  • REST APIs support webhook channel configuration for LIVEBOARD_SCHEDULE events only.

  • You can configure only one webhook per Org for the Liveboard schedule event.

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.

  • Ensure that the REST APIs for setting communication channel preferences and configuring webhooks are enabled on your instance. If the APIs are not available on your instance, contact ThoughtSpot Support.

Configure communication channel preferences🔗

To create a webhook channel, configure channel preferences, and retrieve the channel settings, use the following REST APIs:

Create a webhook communication channel🔗

To create the webhook communication channel and set messaging preferences, send a POST request to the /api/rest/2.0/system/preferences/communication-channels/configure API endpoint. You can set preferences at the cluster level for all Orgs or at the Org level. When both are configured, the preferences set at the Org level take precedence.

Request parameters🔗

ParameterDescription

cluster_preferences

Array of objects. Sets default preferences for all Orgs in the instance. You must specify the following parameters:

event_type

String. Type of event for which communication channels are configured. For the Liveboard schedule event, set the parameter value to LIVEBOARD_SCHEDULE.

channels

Array of strings. Communication channels for the event type specified in the request. Valid values are:

  • EMAIL

  • WEBHOOK

To create a webhook channel for the Liveboard schedule event, specify WEBHOOK.

org_preferences

Array of objects. By default, preferences configured at the cluster level apply to all Orgs in the instance. To override default preferences for your Org, set Org-specific preferences:

org_identifier

String. Name or ID of the Org.

preferences

Array of objects. Define the following parameters to set communication channel preferences for the Org. If preferences are not set, the Org inherits the default preferences applied at the cluster level.

  • event_type
    String. Type of the event for which communication channels are configured. For the Liveboard schedule event, set the parameter value as LIVEBOARD_SCHEDULE.

  • channels
    Array of strings. Communication channels for the event type specified in the request. Valid values are:

    • EMAIL

    • WEBHOOK

    To set up a webhook channel for the Liveboard schedule event, specify WEBHOOK.

operation

String. Type of operation to perform. The following options are available:

  • REPLACE - To replace default preferences.

  • RESET - To restore default preferences. For a reset operation, you must also specify the event type. Note that this operation removes any Org-specific overrides and restores the default preferences configured at the cluster level.

reset_events

Array of strings. For RESET operations, specify the event type to reset. Note that the reset operation removes Org-specific configuration for the events specified in reset_events.

Example request🔗

The following example shows the request body for setting a communication channel preference at the cluster level.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/configure'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "cluster_preferences": [
    {
      "event_type": "LIVEBOARD_SCHEDULE",
      "channels": [
        "WEBHOOK"
      ]
    }
  ]
}'

The following example shows the request body for setting a communication channel preference at the Org level.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/configure'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "org_preferences": [
    {
      "org_identifier": "testOrg1",
      "operation": "REPLACE",
      "preferences": [
        {
          "event_type": "LIVEBOARD_SCHEDULE",
          "channels": [
            "WEBHOOK"
          ]
        }
      ]
    }
  ]
}'

API response🔗

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

View the communication channel preferences🔗

To review and audit the communication channel preferences set on your instance, send a POST request to the /api/rest/2.0/system/preferences/communication-channels/search API endpoint.

Request parameters🔗

ParameterDescription

cluster_preferences
Optional

Array of strings. To filter the API response by event type, specify the event type for which the communication channel preference is set at the cluster level.

org_preferences
Optional

Array of strings. To filter the API response by Org-specific overrides, specify the following parameters:

  • org_identifier
    String. Name or ID of the Org.

  • event_types
    Array of strings. Event types to search for. To get channel preferences for Liveboard schedule events, specify LIVEBOARD_SCHEDULE.

Example request🔗

The following request fetches channel preferences configured for the Liveboard schedule event at the cluster level:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "cluster_preferences": [
    "LIVEBOARD_SCHEDULE"
  ]
}'

The following request fetches channel preferences configured for the Liveboard schedule event at the Org level:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/preferences/communication-channels/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "org_preferences": [
    {
      "org_identifier": "testOrg1",
      "event_types": [
        "LIVEBOARD_SCHEDULE"
      ]
    }
  ]
}'

Example response🔗

If the request is successful, the API returns the channel preference details.

The following example shows the communication channel preferences configured for the specified event type at the cluster level:

{
  "cluster_preferences": [],
  "org_preferences": [
    {
      "org": {
        "id": "0",
        "name": "Primary"
      },
      "preferences": []
    },
    {
      "org": {
        "id": "1532970882",
        "name": "testOrg"
      },
      "preferences": [
        {
          "event_type": "LIVEBOARD_SCHEDULE",
          "channels": [
            "EMAIL",
            "WEBHOOK"
          ]
        }
      ]
    },
    {
      "org": {
        "id": "2100019165",
        "name": "testOrg1"
      },
      "preferences": [
        {
          "event_type": "LIVEBOARD_SCHEDULE",
          "channels": [
            "WEBHOOK"
          ]
        }
      ]
    }
  ]
}

The following example shows the preferences returned for a specific Org:

{
  "cluster_preferences": [],
  "org_preferences": [
    {
      "org": {
        "id": "2100019165",
        "name": "testOrg1"
      },
      "preferences": [
        {
          "event_type": "LIVEBOARD_SCHEDULE",
          "channels": [
            "WEBHOOK"
          ]
        }
      ]
    }
  ]
}

Validate communication channel configuration🔗

To ensure that a communication channel configuration is properly configured and can receive events, use the /api/rest/2.0/system/communication-channels/validate API endpoint and validate the communication channel configuration.

Request parameters🔗

ParameterDescription

channel_type

String. Type of communication channel to validate. Specify WEBHOOK.

channel_identifier

String. ID or name of the communication channel. For webhook channels, specify the webhook ID. You can retrieve the webhook ID via an API request to the POST /api/rest/2.0/webhooks/search endpoint.

event_type

String. Event type associated with the specified channel. For webhook channels, the supported event type is LIVEBOARD_SCHEDULE.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/communication-channels/validate'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "channel_type": "WEBHOOK",
  "channel_identifier": "3791ad80-70e8-4222-bf11-fb8a5f1b5bf4",
  "event_type": "LIVEBOARD_SCHEDULE"
}'

Example response🔗

If the validation is successful, the API returns a response indicating the webhook channel validation state.

The following response shows validation status for a webhook channel:

{
   "channel_type":"WEBHOOK",
   "channel_id":"9185f9be-f237-42bf-b452-c2dc897e1673",
   "channel_name":"Zapier",
   "event_type":"LIVEBOARD_SCHEDULE",
   "job_id":"n.validation-0e55b1de-8c30-48d1-8c73-2f0365e03641",
   "result_code":"SUCCESS",
   "details":[
      {
         "validation_step":"HTTP_CONNECTION_CHECK",
         "status":"SUCCESS",
         "http_status":200,
         "error_message":null,
         "aws_s3_info":null
      }
   ]
}

The following response shows the validation success and failure errors for a webhook channel with AWS s3 storage configuration:

{
   "channel_type":"WEBHOOK",
   "channel_id":"52314c1c-8d1d-40d1-8dba-3f77d219b41a",
   "channel_name":"nebula-webhooks-gcp-05012026-webhook1",
   "event_type":"LIVEBOARD_SCHEDULE",
   "job_id":"n.validation-37688eaf-6cb1-4f7e-a6f2-0658c1d678eb",
   "result_code":"PARTIAL_SUCCESS",
   "details":[
      {
         "validation_step":"STORAGE_FILE_UPLOAD_CHECK",
         "status":"FAILED",
         "http_status":null,
         "error_message":"failed to assume role 'arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole': operation error STS: AssumeRole, https response error StatusCode: 403, RequestID: 8ba1a7a1-65c2-4901-8d4a-bf150687e92c, api error AccessDenied: User: arn:aws:sts::418295724037:assumed-role/cell-89b3a1c7-coms-lambda-role/cell-89b3a1c7-coms-api is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole. Ensure the role's trust policy allows ThoughtSpot and the External ID matches",
         "aws_s3_info":{
            "bucket_name":"my-webhook-files",
            "file_name":"validation_dummy_20260330_131030.pdf",
            "object_key":"webhooks/cluster-abc/org-1/user-123/liveboard/report.pdf"
         }
      },
      {
         "validation_step":"HTTP_CONNECTION_CHECK",
         "status":"SUCCESS",
         "http_status":200,
         "error_message":null,
         "aws_s3_info":null
      }
   ]
}

Monitor webhook delivery and job status🔗

To monitor job status for communication channels such as webhook, use the /api/rest/2.0/jobs/history/communication-channels/search API endpoint.

Request parameters🔗

In the API request, you must provide channel details such as channel type, ID, and event type, or specify the job ID.

ParameterDescription

channel_type

String. Type of communication channel to validate. Specify WEBHOOK for webhook channels.

job_ids

Array of strings. One or more IDs of the job. To get the ID for a given webhook channel, check the API response from the /api/rest/2.0/system/communication-channels/validate endpoint.

Required parameter if no channel identifier and event ID are specified in the API request.

channel_identifiers

String. IDs or names of the communication channel. Required if no job ID is specified. For webhook channels, specify the webhook ID. You can retrieve the webhook IDs from the /api/rest/2.0/webhooks/search API endpoint via an API request.

channel_status

String. Status of the channel or the job. Specify one of the following values:

  • PENDING
    Gets a list of all pending webhook deliveries that are currently queued but not yet attempted.

  • RETRY
    Gets a list of webhook delivery jobs that are in the retry state.

  • SUCCESS
    Gets a list of jobs that were delivered successfully.

  • FAILED
    Gets a list of failed job deliveries.

events
Optional

Allows filtering API response by event type and ID.

  • type
    Event type for which the webhook delivery is triggered. Default is LIVEBOARD_SCHEDULE.

  • identifier
    ID of the event.

start_epoch_time_in_millis

Decimal. Allows filtering API response by records that were created on or after the specified epoch milliseconds.

Example request🔗

The following example shows the sample request with job ID.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/jobs/history/communication-channels/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer c2****************==' \
  --data-raw '{
  "channel_type": "WEBHOOK",
  "job_ids": [
    "n.validation-0e55b1de-8c30-48d1-8c73-2f0365e03641"
  ]
}'

Example response🔗

If your request is successful, the API returns the job details for the specified job or channel ID.

{
   "jobs":[
      {
         "id":"n.validation-0e55b1de-8c30-48d1-8c73-2f0365e03641",
         "status":"SUCCESS",
         "creation_time_in_millis":1774876441988,
         "event":{
            "type":"LIVEBOARD_SCHEDULE",
            "id":"validation-9185f9be-f237-42bf-b452-c2dc897e1673",
            "name":null,
            "run_id":null
         },
         "recipients":null,
         "detail":"",
         "try_count":1
      }
   ]
}

For failed jobs, the status is set to FAILED, and the detail parameter in the API response contains the error details.

{
   "jobs":[
      {
         "id":"n.validation-900ea028-5254-4d38-a03c-26fb41aa632b",
         "status":"FAILED",
         "creation_time_in_millis":1774890524301,
         "event":{
            "type":"LIVEBOARD_SCHEDULE",
            "id":"validation-52314c1c-8d1d-40d1-8dba-3f77d219b41a",
            "name":null,
            "run_id":null
         },
         "recipients":null,
         "detail":"STORAGE_FILE_UPLOAD_CHECK (bucket: my-webhook-files): failed to assume role 'arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole': operation error STS: AssumeRole, https response error StatusCode: 403, RequestID: 25182019-58ca-4003-8048-6713bd7d7d4e, api error AccessDenied: User: arn:aws:sts::418295724037:assumed-role/cell-89b3a1c7-coms-lambda-role/cell-89b3a1c7-coms-api is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole. Ensure the role's trust policy allows ThoughtSpot and the External ID matches",
         "try_count":1
      }
   ]
}

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.