# Configure and monitor communication channels > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/webhooks-comm-channel # Configure 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]({{navprefix}}/{{webhooks-comm-channel}}#_configure_communication_channel_preferences), [validate configuration]({{navprefix}}/{{webhooks-comm-channel}}#_validate_communication_channel_configuration), and [monitor the health and status of communication channels]({{navprefix}}/{{webhooks-comm-channel}}#_monitor_webhook_delivery_and_job_status) using REST APIs. > **NOTE:** REST APIs support webhook channel configuration for LIVEBOARD\_SCHEDULE events only. ## 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 privilege: - `APPLICATION_ADMINISTRATION` (**Can manage application settings**) to create and view communication channel preferences. - 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: - [`POST /api/rest/2.0/system/preferences/communication-channels/configure`]({{navprefix}}/{{webhooks-comm-channel}}#_create_a_webhook_communication_channel) - [`POST /api/rest/2.0/system/preferences/communication-channels/search`]({{navprefix}}/{{webhooks-comm-channel}}#_view_the_communication_channel_preferences) ### 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 | Parameter | Description | | | --- | --- | --- | | `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 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 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 | Parameter | Description | | --- | --- | | `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 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 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: ```JSON { "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: ```JSON { "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 is properly configured and can receive events, use the `/api/rest/2.0/system/communication-channels/validate` API endpoint to validate the communication channel configuration. ### Request parameters | Parameter | Description | | --- | --- | | `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 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 The following response shows validation status for a webhook channel: ```JSON { "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: ```JSON { "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 webhooks, 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. | Parameter | Description | | --- | --- | | `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 if neither a channel identifier nor an event ID is specified in the API request. | | `channel_identifiers` | _Array of strings_. 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. | | `end_epoch_time_in_millis` | _Decimal_. Filters the API response by records created before the specified timestamp (in epoch milliseconds). | ### Example request The following example shows a sample request with a job ID. ```cURL 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. ```JSON { "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. ```JSON { "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 - [Deliver Liveboard reports to an external application]({{navprefix}}/{{webhooks-lb-schedule}}). - [Deliver Liveboard reports to AWS S3 storage bucket]({{navprefix}}/{{webhooks-s3-storage}}). - [GCS storage integration for webhook delivery]({{navprefix}}/{{webhooks-gcs-storage}}).