Webhooks

Table of Contents

Overview
Webhook configuration and management
- Webhooks UI
- Webhook REST APIs
Webhook delivery behavior
Webhook payload
Next steps

ThoughtSpot webhooks provide a way to deliver data and reports to a target application, URL endpoint, or storage destination, triggered by events such as scheduled Liveboard jobs.

Overview🔗

ThoughtSpot allows using webhooks for the following purposes:

Liveboard schedule notifications

ThoughtSpot supports using webhooks to deliver scheduled Liveboard notifications to external applications and communication channels. For more information, see Webhook configuration for Liveboard scheduled events.

Webhook delivery to Cloud Storage destinations

ThoughtSpot supports delivering webhook payloads to the following cloud storage destinations:

Amazon S3: Available on AWS-hosted and GCP-hosted ThoughtSpot Cloud instances. For configuration steps, see AWS S3 storage configuration for webhooks.
Google Cloud Storage (GCS): Available on GCP-hosted ThoughtSpot Cloud instances. For more information, see GCS storage configuration for webhooks.

KPI monitor alerts

You can use a webhook to trigger KPI monitor alerts to an external application when a KPI metric meets a threshold condition or changes value. For more information, see Webhooks for KPI monitor alerts.

Webhook configuration and management🔗

ThoughtSpot supports creating and managing webhooks through the UI or REST APIs.

Note

To set up a webhook for Liveboard schedule notifications, you must first configure the webhook communication channel using the communication-channel preferences API.
Only one webhook per Org is allowed for the Liveboard Schedule event type.
To configure and manage webhooks, ADMINISTRATION (Can administer ThoughtSpot) or Can manage webhooks (CAN_MANAGE_WEBHOOKS) privilege is required.

Webhooks UI🔗

For managing webhooks via UI, use the following options in the Develop page of the ThoughtSpot UI:

Webhooks :
The new Webhooks option in the Develop page provides a centralized view of webhooks configured in ThoughtSpot, including the options to create, monitor, and manage webhooks, and view delivery statistics and logs in your ThoughtSpot Org.

Important

The new Webhooks UI experience is in Beta and is disabled by default. To enable this feature, contact ThoughtSpot Support.
In the current version, the new experience allows creating and managing webhooks for Liveboard Schedule events only.

For more information, see Webhook configuration and management through the UI.

Legacy Webhooks: The Legacy webhooks page displays a list of webhooks created for KPI alerts and the menu actions to create, view, and edit the webhooks created for KPI alerts. These webhooks are managed through the UI and can be selected as custom channels to send KPI alerts when a KPI metric meets the threshold. For more information, see Webhook configuration and management through the UI and Webhooks for KPI monitor alerts.

Webhook REST APIs🔗

The REST API framework is intended for automation and integration scenarios, for example, creating webhooks programmatically or delivering Liveboard report attachments to a cloud storage destination. For REST API reference and examples, see Deliver Liveboard reports to an external application and Webhook REST APIs.

Webhook delivery behavior🔗

When ThoughtSpot attempts to deliver a webhook event, the destination endpoint must respond with an HTTP 2xx status code within 5 seconds to confirm successful receipt.

If the endpoint takes longer than 5 seconds to respond, returns a non-2xx status code, or times out, ThoughtSpot records the delivery status as FAILED and retries the request.

To ensure a timely response, process webhook payloads asynchronously. Your server can return a 2xx response immediately on receipt and handle the payload in the background, without blocking subsequent webhook deliveries.

For information about retry behavior and delivery logs, see Manage webhooks.

Webhook payload🔗

The payload that ThoughtSpot sends depends on the destination:

Destination Payload

Destination	Payload
HTTP endpoint (Liveboard schedule)	A `multipart/form-data` request with a `payload` part that contains the metadata JSON, followed by one part for each attached file. The total size of all attachments is limited to approximately 22 MB.
AWS S3 or GCS storage	Metadata JSON that includes the storage object URL. The files are uploaded to your storage bucket and are not included in the request.

HTTP endpoint (Liveboard schedule)

A multipart/form-data request with a payload part that contains the metadata JSON, followed by one part for each attached file. The total size of all attachments is limited to approximately 22 MB.

AWS S3 or GCS storage

Metadata JSON that includes the storage object URL. The files are uploaded to your storage bucket and are not included in the request.

Make sure that your HTTP endpoint:

Parses multipart/form-data requests, not JSON. For the payload structure, see Webhook payload for Liveboard events.
Accepts request bodies of at least 25 MB. ThoughtSpot sends up to approximately 22 MB of attachments in a single delivery, and the request also includes the metadata and multipart headers. If your endpoint rejects the request, it may return an HTTP 413 Payload Too Large error and the delivery fails.

Gateways and proxies in front of your endpoint may enforce lower limits. If your reports may exceed these limits, use AWS S3 or GCS storage instead.