GCS storage configuration for webhooks

Table of Contents

Before you begin
Grant service account impersonation permissions
Configuring a webhook with GCS storage
- Using REST API
- Using Webhooks page in UI
Webhook payload format in GCS
Viewing webhook configuration details
Validating webhook channel configuration
Monitoring webhook delivery status
Verifying delivery
Troubleshooting errors
Related topics

^Beta

If your ThoughtSpot instance is hosted on Google Cloud Platform (GCP), you can configure a webhook to deliver payloads and file attachments from a scheduled Liveboard event to your Google Cloud Storage (GCS) bucket.

Note	GCS storage integration for webhooks is available for GCP-hosted ThoughtSpot instances only. This feature is in Beta. To enable this feature on your instance, contact ThoughtSpot Support.

Important

The new Webhooks UI experience is an Early Access feature and is disabled by default. To enable this feature, contact ThoughtSpot Support.
The new Webhooks UI experience is available only on ThoughtSpot Cloud instances running 26.7.0.cl and later.
In the current version, the new experience allows creating and managing webhooks for Liveboard Schedule events only.

Before you begin🔗

Before configuring GCS storage for webhooks:

Ensure that webhook support for GCS destination is enabled on your cluster. If the feature is not available on your cluster, contact ThoughtSpot Support to enable it.
For GCS storage destination configuration, you’ll need the platform GCP service account email and the IAM role to grant for service account impersonation. To retrieve these details, send a GET request to the /api/rest/2.0/webhooks/storage-config API endpoint.
Ensure that you have a GCS bucket in the same GCP project or a project that allows cross-project IAM bindings.
To configure a webhook in ThoughtSpot, you’ll need a user account with administration privileges or the Can Manage Webhooks role privilege. Ensure that you have the required privileges to set up webhook connection and monitor delivery status.
Ensure that a webhook communication channel is configured in your Org or at the cluster level on your instance.

Grant service account impersonation permissions🔗

In the GCP Console or using the gcloud CLI, grant the ThoughtSpot service account the roles/iam.serviceAccountTokenCreator role on your GCS-enabled service account:

gcloud iam service-accounts add-iam-policy-binding <your-service-account-email> \
  --member="serviceAccount:<ts-service-account-email>" \
  --role="roles/iam.serviceAccountTokenCreator"

Note	This grants ThoughtSpot’s service account the ability to create short-lived credentials for your service account, enabling it to write to your GCS bucket on your behalf without requiring long-lived credentials to be shared.

Configuring a webhook with GCS storage🔗

To create a webhook in ThoughtSpot, the webhook feature must be enabled on your instance. Only ThoughtSpot users with administration privileges or the Can Manage Webhooks privilege are allowed to create or manage a webhook.

You can create a webhook with a cloud storage destination using the Webhooks page in the UI or through the create webhook REST API.

Using REST API🔗

To configure the GCS storage properties in ThoughtSpot, the service account email and GCS bucket name are required.

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

Note	ThoughtSpot allows only one webhook for the Liveboard Schedule event type 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 listening endpoint URL where the webhook payload will be sent. The payload will include metadata and a URL referencing the file stored in GCS.
`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 the event as `LIVEBOARD_SCHEDULE`. When this event is emitted, a webhook payload is initiated to send data to the configured GCS storage destination.
`storage_destination`	Configuration for storage destination. Specify the following parameters: * `storage_type` String. Type of storage destination. Specify `GCP_GCS`. `storage_config` Storage configuration parameters. For `gcp_gcs_config`, specify the following parameters: `bucket_name` String. Name of the GCS bucket where webhook payloads will be stored. For example, `ts-webhook-exports`. `service_account_email` String. Email of the GCP service account to impersonate for bucket access. For example, `[email protected]`. The platform’s service account must be granted `roles/iam.serviceAccountTokenCreator`. `path_prefix` Optional String. Path prefix for organizing objects within the bucket. For example, `thoughtspot/`.
`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. You can use this parameter to pass arbitrary headers with custom metadata in key-value pairs, as required by the webhook receiver endpoint. When configured, ThoughtSpot sends these headers in addition to the authentication headers and standard HTTP headers such as `Content-Type`, `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 listening endpoint URL where the webhook payload will be sent. The payload will include metadata and a URL referencing the file stored in GCS.

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 the event as LIVEBOARD_SCHEDULE. When this event is emitted, a webhook payload is initiated to send data to the configured GCS storage destination.

storage_destination

Configuration for storage destination. Specify the following parameters: * storage_type
String. Type of storage destination. Specify GCP_GCS.

storage_config
Storage configuration parameters. For gcp_gcs_config, specify the following parameters:
bucket_name
String. Name of the GCS bucket where webhook payloads will be stored. For example, ts-webhook-exports.
service_account_email
String. Email of the GCP service account to impersonate for bucket access. For example, [email protected]. The platform’s service account must be granted roles/iam.serviceAccountTokenCreator.
path_prefix Optional
String. Path prefix for organizing objects within the bucket. For example, thoughtspot/.

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. You can use this parameter to pass arbitrary headers with custom metadata in key-value pairs, as required by the webhook receiver endpoint. When configured, ThoughtSpot sends these headers in addition to the authentication headers and standard HTTP headers such as Content-Type, User-Agent.

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

API 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-gcs",
  "url": "https://webhook-destination-site.com",
  "events": [
    "LIVEBOARD_SCHEDULE"
  ],
  "description": "Webhook delivery to GCS bucket",
  "storage_destination": {
    "storage_type": "GCP_GCS",
    "storage_config": {
      "gcp_gcs_config": {
        "bucket_name": "my-webhook-files",
        "service_account_email": "[email protected]",
        "path_prefix": "thoughtspot/"
      }
    }
  },
  "status": "ENABLED"
}'

API response🔗

The API response includes both aws_s3_config and gcp_gcs_config fields within storage_config. When GCS is configured, aws_s3_config appears as null.

{
   "id":"18835251-668b-4851-b5c7-35358549f3f4",
   "name":"webhook-gcs",
   "description":"Webhook for GCS delivery",
   "org":{
      "id":"0",
      "name":"test-org"
   },
   "url":"https://webhook-destination-site.com",
   "url_params":null,
   "events":[
      "LIVEBOARD_SCHEDULE"
   ],
   "authentication":null,
   "signature_verification":null,
   "additional_headers":null,
   "creation_time_in_millis":1782867500837,
   "modification_time_in_millis":1782867500837,
   "created_by":{
      "id":"59481331-ee53-42be-a548-bd87be6ddd4a",
      "name":"tsadmin"
   },
   "last_modified_by":null,
   "storage_destination":{
      "storage_type":"GCP_GCS",
      "storage_config":{
         "aws_s3_config":null,
         "gcp_gcs_config":{
            "bucket_name":"my-webhook-files",
            "service_account_email":"[email protected]",
            "path_prefix":"thoughtspot/"
         }
      }
   },
   "status":"ENABLED"
}

Using Webhooks page in UI🔗

If the new Webhooks page is enabled on your instance, you can create a webhook via the UI. To create a webhook with GCS as the target destination for payload delivery:

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.
To configure storage destination, select the File storage checkbox and specify values for the following properties:
- Storage provider: Select Google Cloud Storage (GCS).
- Bucket name: Name of the GCS bucket. For example, my-webhook-files.
- Service account email: Email of the GCP service account to impersonate for bucket access.
- Path prefix: Optional. Path prefix for organizing objects within the bucket. For example, thoughtspot/.
To configure advanced settings such as signature verification, custom headers, and URL query parameters, click Advanced settings and configure the fields as required.
Click Save.
If the webhook is created successfully, it is added to the Webhooks list and enabled by default.

Webhook payload format in GCS🔗

ThoughtSpot writes each webhook event as a separate object in your GCS bucket. Objects are named using the following pattern:

<object_prefix>/<event-type>/<timestamp>-<event-id>.json

Viewing webhook configuration details🔗

To view the webhook details, use one of the following options:

Through the REST API:
To retrieve webhook configuration details, use the /api/rest/2.0/webhooks/search API endpoint.
Using the UI:
If the new Webhook experience is enabled on your instance, go to the Develop > Customization > Webhooks page. Check the list in the Webhooks to view the details and verify if the webhook connection is activated.

Validating webhook channel configuration🔗

To validate webhook configuration status, use one of the following options.

Using REST API: To validate the communication channel configuration for webhook delivery, use the /api/rest/2.0/system/communication-channels/validate API endpoint.
Using the UI:
If the new Webhook experience is enabled on your instance, go to the Develop > Customization > Webhooks page. The Webhooks page displays a list of webhooks configured in the current Org context.
To validate the webhook channel configuration:
1. In the Webhooks page, select the webhook row, and click Send test event.
2. Verify the delivery status.

If the validation returns errors, update the webhook configuration properties to resolve the errors.

Monitoring webhook delivery status🔗

To monitor the webhook delivery and status, use one of the following options:

Through the REST API:
To verify 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.
Using the UI:
If your ThoughtSpot instance has new Webhooks page enabled, use the Webhooks menu option on the Develop page to view the details of the webhook:
1. Go to the Develop > Customization > Webhooks page.
  The Webhooks page displays status cards and delivery rate for the webhooks configured in the Org.
2. Click the webhook from the list and verify the delivery details. For more information, see Monitoring delivery status.

Verifying delivery🔗

To verify that ThoughtSpot is delivering webhooks to your GCS bucket:

In the GCP Console, navigate to your bucket and check for new objects.
Verify whether the webhook payload is delivered to the correct bucket and prefix.
Review the object content to confirm the payload matches the expected schema.
Verify the attachments and timestamps in the logs.
If files are not delivered to your GCS bucket, check the logs for errors.

Troubleshooting errors🔗

Issue Resolution

Issue	Resolution
Objects are not delivered to the bucket	This error occurs in the following scenarios: * When service account impersonation fails * When the GCS write operation fails due to permission errors * Webhook connection configuration errors To resolve: * Verify that the ThoughtSpot service account is granted the `roles/iam.serviceAccountTokenCreator` role on your GCS-enabled service account. * Verify that your service account has write access to the GCS bucket. * Verify that the service account email in the webhook configuration matches the service account used to grant permissions.
`permission denied` error in webhook logs	The service account may have been rotated. Retrieve the current service account email using the storage config API and re-grant IAM permissions.
Webhook is configured but not triggering	Verify that the webhook is enabled and that the alert condition for the scheduled event is met. Contact ThoughtSpot Support if the issue persists.

Objects are not delivered to the bucket

This error occurs in the following scenarios:

* When service account impersonation fails * When the GCS write operation fails due to permission errors * Webhook connection configuration errors

To resolve:

* Verify that the ThoughtSpot service account is granted the roles/iam.serviceAccountTokenCreator role on your GCS-enabled service account. * Verify that your service account has write access to the GCS bucket. * Verify that the service account email in the webhook configuration matches the service account used to grant permissions.

permission denied error in webhook logs

The service account may have been rotated. Retrieve the current service account email using the storage config API and re-grant IAM permissions.

Webhook is configured but not triggering

Verify that the webhook is enabled and that the alert condition for the scheduled event is met. Contact ThoughtSpot Support if the issue persists.