Deliver content to AWS S3 storage using webhooks
26.3.0.cl
Cloud (Latest)

Deliver content to AWS S3 storage using webhooks

Beta

ThoughtSpot can deliver webhook payloads, such as scheduled Answer or Liveboard exports, as files written directly to your S3 storage. When integrated, ThoughtSpot supports delivering payloads of up to 25 MB directly to the storage destination configured on your instance.

Before you begin🔗

Before you begin, review the following prerequisites and ensure that you have the required setup for webhook configuration:

  • Ensure that you have access to a ThoughtSpot instance with the Webhook feature enabled.

  • Identify the environment in which your instance is deployed. Currently, S3 storage integration is supported in application instances hosted in one of the following environments:

    • ThoughtSpot instances hosted in Amazon Web Services (AWS)

    • ThoughtSpot instances hosted in Google Cloud Platform (GCP)

  • Ensure that you have an AWS account where the target S3 bucket will be hosted.

  • Ensure that you have AWS permissions to:

    • 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 a webhook communication channel is configured in your Org or at the cluster level on your instance.

AWS-based 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:

RequirementDescription

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.

{
  "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.

{
  "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.

GCP-based 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 are required:

RequirementDescription

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

{
  "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.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/thoughtspot-webhooks/*"
    }
  ]
}

Provide the storage configuration details to 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/.

Configure 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.

Currently, ThoughtSpot supports webhook creation with AWS S3 storage via REST APIs only.

Create a webhook🔗

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 per Org.

Request parameters🔗

ParameterDescription

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. Specify the storage configuration parameters from your AWS account administrator.

  • 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. S3 prefix for the folder. For example, thoughtspot/.

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_S3",
  "url": "https://api.example.com/thoughtspot/webhook",
  "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.

{
   "id":"e63886a8-d468-4fc8-9c9b-a72bab6c4aee",
   "name":"name6",
   "description":null,
   "org":{
      "id":"0",
      "name":"Primary"
   },
   "url":"https://api.example.com/thoughtspot/webhook",
   "url_params":{
      "key":"value"
   },
   "events":[
      "LIVEBOARD_SCHEDULE"
   ],
   "authentication":null,
   "signature_verification":null,
   "creation_time_in_millis":1772100928376,
   "modification_time_in_millis":1772100928376,
   "created_by":{
      "id":"61b37746-a9bc-4433-b0cb-7a0e03225932",
      "name":"demo_devuser"
   },
   "last_modified_by":null,
   "storage_destination":{
      "storage_type":"AWS_S3",
      "storage_config":{
         "aws_s3_config":{
            "bucket_name":"ts-webhook-x7k9m2p4q1",
            "region":"us-east-1",
            "role_arn":"arn:aws:iam::999888777666:role/thoughtspot-s3-upload",
            "external_id":"ts-webhook-x7k9m2p4q1",
            "path_prefix":"thoughtspot/"
         }
      }
   }
}

Update the properties of a webhook🔗

To update the S3 storage details configured for a webhook, send a POST request to the /api/rest/2.0/webhooks/{webhook_identifier}/update API endpoint.

Request parameters🔗

Specify the webhook_identifier and pass it as a path parameter in the request URL.

The API operation allows you to update the following webhook properties:

  • name
    Name of the webhook.

  • description
    Description text of the webhook.

  • url
    The URL of the webhook endpoint.

  • url_params
    Query parameters to append to the endpoint URL.

  • events
    Events subscribed to the webhook. In the current release, ThoughtSpot supports only the LIVEBOARD_SCHEDULE event.

  • storage_destination
    S3 storage destination.

  • storage_type
    Type of storage destination. Currently, only the Amazon S3 bucket is supported as the storage destination.

  • storage_config
    S3 storage configuration parameters:

API request🔗

The following example shows the request body for updating the name, description text, and endpoint URL of a webhook object:

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/{webhook_identifier}/update' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "name": "name6",
  "url": "https://api.example.com/thoughtspot/webhook",
  "events": [
    "LIVEBOARD_SCHEDULE"
  ],
  "url_params": {
    "key": "value"
  },
  "storage_destination": {
    "storage_type": "AWS_S3",
    "storage_config": {
      "aws_s3_config": {
        "bucket_name": "ts-webhook-x7k9m2p4q1",
        "region": "us-east-1",
        "role_arn": "arn:aws:iam::999888777666:role/thoughtspot-s3-upload",
        "external_id": "ts-webhook-x7k9m2p4q1",
        "path_prefix": "thoughtspot/webhook"
      }
    }
  }
}'

API response🔗

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

Verify the integration🔗

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 test the integration:

  1. Trigger a Liveboard scheduled export to the configured S3 storage destination.

  2. In your S3 bucket:

    • Confirm whether the webhook payload is delivered to the correct bucket and prefix.

    • Verify the attachments and timestamps in the AWS event logs.

  3. If files are not delivered to your S3 bucket, check the logs for errors.

Troubleshooting errors🔗

The common causes for webhook delivery failure are:

  • Access denied errors

  • Invalid external ID

  • Webhook configuration errors in ThoughtSpot

Access denied errors🔗

The access denied error occurs in the following scenarios:

  • When the IAM role assumption fails

  • When the S3 upload fails due to permission errors

To resolve IAM role assumption issues:

  • Ensure that the IAM trust policy includes the correct ThoughtSpot service account ID.
    For GCP clusters, the trust policy must use a federated principal. Verify that the OIDC provider URL and identity are configured for the ThoughtSpot service account ID (THOUGHTSPOT_SA_UNIQUE_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.

Configuration errors🔗

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.

Configuration compatibility🔗

If you are using encryption, lifecycle policies, or special access controls, ensure that they are compatible with your webhook configuration.

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.