# GCS storage configuration for webhooks > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/webhooks-gcs-storage # GCS storage configuration for webhooks 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]({{navprefix}}/{{webhooks-api}}#_retrieving_storage_information_for_webhook_configuration), 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]({{navprefix}}/{{webhooks-comm-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: ```bash gcloud iam service-accounts add-iam-policy-binding \ --member="serviceAccount:" \ --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 | | --- | --- | | `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, `my-sa@my-project.iam.gserviceaccount.com`. 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`. ```JSON "additional_headers": [ { "key":"X-Custom-Header", "value":"custom_value" } ] ``` | #### API request ```cURL 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": "my-sa@my-project.iam.gserviceaccount.com", "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`. ```JSON { "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":"my-sa@my-project.iam.gserviceaccount.com", "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: 1. Go to **Develop** > **Customizations** and click **Webhooks**. 2. In the **Webhooks** page, click **Create webhook**. 3. 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. 4. 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/`. ![Webhooks for GCS storage](/docs/doc-images/images/webhook-create-gcp.png) 5. To configure advanced settings such as signature verification, custom headers, and URL query parameters, click **Advanced settings** and configure the fields as required. 6. 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: //-.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]({{navprefix}}/{{webhooks-api}}#_getting_a_list_of_webhooks). - 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**]({{navprefix}}/{{webhooks-ux}}#_webhooks_list_page) 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]({{navprefix}}/{{webhooks-comm-channel}}#_validate_communication_channel_configuration). - 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]({{navprefix}}/{{webhooks-comm-channel}}#_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]({{navprefix}}/{{webhooks-ux}}#_monitoring_webhook_status). ## Verifying delivery To verify that ThoughtSpot is delivering webhooks to your GCS bucket: 1. In the GCP Console, navigate to your bucket and check for new objects. 2. Verify whether the webhook payload is delivered to the correct bucket and prefix. 3. Review the object content to confirm the payload matches the expected schema. 4. Verify the attachments and timestamps in the logs. 5. If files are not delivered to your GCS bucket, check the logs for errors. ## Troubleshooting errors | 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. | ## Related topics - See also: [Webhooks overview]({{navprefix}}/{{webhooks}}), [Webhooks UI]({{navprefix}}/{{webhooks-ux}}), and [Webhook APIs]({{navprefix}}/{{webhooks-api}}) documentation. - [Google Cloud Storage IAM roles](https://cloud.google.com/storage/docs/access-control/iam-roles) documentation.