# AWS S3 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-s3-integration # AWS S3 storage configuration for webhooks Beta ThoughtSpot can deliver webhook payloads and file attachments from a scheduled Liveboard event to your cloud storage bucket. When configured, ThoughtSpot can send payloads of up to 25 MB directly to the storage destination configured for the webhook delivery on your instance. ## Before you begin Before you begin, review the following prerequisites and ensure that you have the required setup for webhook configuration: - Identify the environment in which your instance is deployed. For example, Amazon Web Services (AWS) and Google Cloud Platform (GCP). For S3 destination integration for webhook delivery, the platform AWS account ID and IAM trust policy template are required. 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 an AWS account where the target S3 bucket is hosted with the following permissions: - manage IAM identity providers and roles, including trust policies - attach or edit IAM policies - read and write to the target S3 bucket to test and validate integration - 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. ## S3 storage configuration for AWS-hosted ThoughtSpot instances If your ThoughtSpot instance is running in AWS, you can configure AWS cross-account access with an IAM role that AWS STS can assume by using temporary credentials. For webhook integration, the following configuration setup is required: | Requirement | Description | | --- | --- | | AWS account ID | The AWS account ID associated with your ThoughtSpot instance. To obtain the account ID, contact your ThoughtSpot representative. You must allow this ID to access your S3 resources and grant the required permissions. | | AWS S3 bucket | Create an S3 bucket or use an existing S3 bucket that you intend to use as a storage destination for ThoughtSpot exports. You can also add a prefix, for example, `thoughtspot/`, to logically separate ThoughtSpot files. This serves as the S3 prefix for webhook delivery. | | Cross-account IAM role | The IAM role that ThoughtSpot will assume to deliver webhook content to an S3 bucket. For example, `thoughtspot-s3-upload`. The IAM role must include the following policies: **Trust policy** A trust policy to allow the ThoughtSpot AWS account ID obtained from ThoughtSpot to assume the role. The IAM role’s trust policy must allow ThoughtSpot’s AWS account to call `sts:AssumeRole`. The trust policy must also include an external ID. The external ID is a unique random string that helps prevent unauthorized access. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::YOUR-ACCOUNT-ID:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "YOUR-EXTERNAL-ID" } } } ] } ``` **Permissions policy** A permissions policy granting only the necessary S3 actions on your chosen bucket prefix. In the permissions policy, specify the S3 bucket name. Optionally, to restrict access to a specific folder or prefix, you can add the prefix. ```JSON { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/thoughtspot/*" } ] } ``` Note the IAM role ARN, bucket name, external ID, and other attributes and save the IAM policies. | ## S3 storage configuration for GCP-hosted ThoughtSpot instances If your ThoughtSpot instance is hosted on a GCP cluster, you must configure OIDC and AWS STS `AssumeRoleWithWebIdentity` so that ThoughtSpot can securely obtain temporary AWS credentials to upload files to your S3 bucket, without storing long-lived AWS access keys. For webhook integration, the following information is required: | Requirement | Description | | --- | --- | | ThoughtSpot service account ID | Contact ThoughtSpot Support to obtain your account ID. This account ID is required for OIDC identity creation and trust policy configuration. | | AWS S3 bucket | Create an S3 bucket or use an existing S3 bucket that you intend to use as a storage destination for ThoughtSpot exports. You can also add a prefix, for example, `thoughtspot-webhooks/`, to logically separate ThoughtSpot files. This serves as the S3 prefix for webhook delivery. | | OIDC provider URL | Add the OIDC identity provider URL in the AWS console. For example, `accounts.google.com`. | | AWS IAM role | The IAM role that ThoughtSpot can assume via `AssumeRoleWithWebIdentity` during upload. **Web Identity trust policy** A trust policy that allows GCP service account via the identity provider. Ensure that the IAM role’s trust policy is restricted using `sub` (subject) and `aud` (audience) attributes: - `sub`: ThoughtSpot GCP service account unique ID - `aud`: ThoughtSpot GCP service account unique ID ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/accounts.google.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "accounts.google.com:sub": "THOUGHTSPOT_SA_UNIQUE_ID", "accounts.google.com:aud": "THOUGHTSPOT_SA_UNIQUE_ID" } } } ] } ``` Where: - `YOUR_AWS_ACCOUNT_ID` is your AWS account ID - `THOUGHTSPOT_SA_UNIQUE_ID` is the ID provided by ThoughtSpot. **Permissions policy** A permissions policy granting only the necessary S3 actions on your chosen bucket prefix. In the permissions policy, specify the role ARN and S3 bucket name. Optionally, to restrict access to a specific folder or prefix, you can add the prefix. ```JSON { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/thoughtspot-webhooks/*" } ] } ``` | ## Storage configuration details for ThoughtSpot Provide the following information to your ThoughtSpot administrator: - AWS Role ARN. For example, `arn:aws:iam::999888777666:role/thoughtspot-s3-upload` - External ID. For example, `ts-webhook-x7k9m2p4q1`. Required for configuring a webhook on ThoughtSpot instances hosted in AWS. Not applicable to ThoughtSpot instances on GCP. - S3 bucket name. For example, `ts-data-exports` - S3 region. For example, `us-east-1` - S3 prefix for the folder (optional). For example, `thoughtspot/`. ## Configuring a webhook for the S3 storage destination in ThoughtSpot 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 S3 storage properties in ThoughtSpot, the IAM role, external ID, S3 bucket name, and S3 region configured in your AWS account 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 S3. | | `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 S3 storage destination. | | `storage_destination` | Configuration for storage destination. Specify the following parameters: \* `storage_type` _String_. Type of storage destination. Specify `AWS_S3`. - `storage_config` Storage configuration parameters. For `aws_s3_config`, specify the following parameters: - `bucket_name` _String_. S3 bucket name. For example, `ts-data-exports` - `region` _String_. S3 region. For example, `us-east-1` - `role_arn` _String_. IAM role ARN. For example, `arn:aws:iam::999888777666:role/thoughtspot-s3-upload` - `external_id` _String_. The External ID string in IAM role trust policies that grant access to your AWS resources. For example, `ts-webhook-x7k9m2p4q1`. This parameter is required for AWS-hosted instances and is not applicable to GCP-hosted ThoughtSpot instances. - `path_prefix` _Optional_ _String_. Path prefix for organizing objects within the S3 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. 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: ```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_S3", "url": "https://webhook-destination-site.com", "events": [ "LIVEBOARD_SCHEDULE" ], "storage_destination": { "storage_type": "AWS_S3", "storage_config": { "aws_s3_config": { "bucket_name": "my-company-data-exports", "region": "us-east-1", "role_arn": "arn:aws:iam::999888777666:role/thoughtspot-s3-upload", "external_id": "ts-webhook-x7k9m2p4q1", "path_prefix": "thoughtspot/" } } } }' ``` #### API response If the API request is successful, ThoughtSpot returns the webhook configuration properties in the API response. ```JSON { "id":"875f1497-fc98-436e-af59-28dc74dc324e", "name":"webhook-S3", "description":"Webhook for S3", "org":{ "id":"2100019165", "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":1782867817910, "modification_time_in_millis":1782867817910, "created_by":{ "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", "name":"user@thoughtspot.com" }, "last_modified_by":null, "storage_destination":{ "storage_type":"AWS_S3", "storage_config":{ "aws_s3_config":{ "bucket_name":"my-company-data-exports", "region":"us-east-1", "role_arn":"arn:aws:iam::999888777666:role/thoughtspot-s3-upload", "external_id":"ts-webhook-x7k9m2p4q1", "path_prefix":"thoughtspot/" }, "gcp_gcs_config":null } }, "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 an AWS S3 storage 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**: For AWS S3 storage, ensure that **Amazon S3** is selected. - **Bucket name**: Name of the S3 bucket. For example, `my-company-data-exports`. - **Region**: S3 region. For example, `us-east-1` - **Role ARN**: AWS Role ARN. For example, `arn:aws:iam::999888777666:role/thoughtspot-s3-upload` - **External ID**: External ID. For example, `ts-webhook-x7k9m2p4q1`. Required for configuring a webhook on ThoughtSpot instances hosted in AWS. Not applicable to ThoughtSpot instances on GCP. - **Path prefix**: Optional. Path prefix for organizing objects within the S3 bucket. For example, `thoughtspot/`. ![Webhooks creation](/docs/doc-images/images/create-webhook-s3.png) 5. To configure [advanced settings]({{navprefix}}/{{webhooks-ux}}#_creating_a_webhook) 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. ## 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 in 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 webhook delivery Webhook delivery to an S3 storage destination includes the following sequence of events: 1. ThoughtSpot requests temporary AWS credentials by calling `sts:AssumeRole` (AWS setup) or `sts:AssumeRoleWithWebIdentity` (GCP) with your specified Role ARN and External ID. 2. AWS Security Token Service (STS) checks the request against your trust policy. 3. If the request is valid, AWS STS issues temporary credentials, valid for approximately an hour. 4. ThoughtSpot uses these credentials to upload files to your designated S3 bucket. To verify that ThoughtSpot is delivering webhooks to your S3 bucket: 1. Access your S3 bucket. 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 S3 bucket, check the logs for errors. ## Troubleshooting errors The common causes for webhook delivery failure are: | Issue | Resolution | | --- | --- | | Objects not delivered to the bucket | This occurs in the following scenarios: \* When the IAM role assumption fails \* When the S3 upload fails due to permission errors \* Webhook connection configuration errors To resolve IAM role assumption issues: \* Ensure that the IAM trust policy includes the correct ThoughtSpot service account ID. \* Ensure that ThoughtSpot is assigned AWS credentials via `sts:AssumeRole` (for AWS) or `sts:AssumeRoleWithWebIdentity` (for GCP) for the specified Role ARN and External ID. To resolve S3 upload permission errors: Ensure that the IAM permission or S3 bucket policy allows the IAM role to write objects and has the correct S3 actions configured. To write content to the S3 bucket, the `s3:PutObject` permission is required. S3 uploads can also fail due to errors in webhook configuration in ThoughtSpot. ThoughtSpot can control which buckets can be accessed, what actions are permitted, and when to revoke access. However, ThoughtSpot cannot read files in existing S3 storage that is not integrated with webhooks, access other prefixes, or view or modify objects in the bucket. To ensure that there is no mismatch in the configuration: \* Verify the external ID used in the webhook configuration. Note that external IDs are case-sensitive. \* Ensure that the S3 bucket name and Role ARN configured in ThoughtSpot match the S3 bucket name and ARN of the IAM role in your AWS account. | | 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. | | Configuration compatibility issues | If you are using encryption, lifecycle policies, or special access controls, ensure that they are compatible with your webhook configuration. | ## Additional resources - See also: [Webhooks overview]({{navprefix}}/{{webhooks}}), [Webhooks UI]({{navprefix}}/{{webhooks-ux}}), and [Webhook APIs]({{navprefix}}/{{webhooks-api}}) documentation. - [AWS IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) and [IAM and Amazon S3 troubleshooting guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-s3.html).