Webhooks

Overview

Webhooks let other applications subscribe to be notified when certain events happen in your Analyst Studio Workspace. You can use webhooks to do automate workflows and trigger other applications. For example:

  • Trigger a Zap in Zapier.

  • Send a customized Slack alert when an Analyst Studio Report finishes running.

  • Log usage of your Analyst Studio Workspace.

When you set up a webhook, Analyst Studio will send a POST message to a URL of your choice in real-time. The message payload contains the name of the event and a link to the API endpoint associated with that event. Analyst Studio’s webhooks are designed to be light-weight and secure, since the payload itself does not contain sensitive information.

We’ll periodically add support for new webhook events.

Create and subscribe to a webhook

  1. On the top left of Analyst Studio home page, click on your account and select Workspace Settings.

  2. Select Webhooks from the left navigation panel and then click Add New Webhook.

  3. Add a Target URL, Description, and an event to subscribe to.

  4. When you click Create Webhook, Analyst Studio will send a test event to the target URL to make sure the response is successful.

Currently, only admins can enable webhooks. Non-admins will need to contact a workspace admin to initialize Webhooks. Once the webhooks are enabled, any user is able to construct logic that utilizes the data sent by these webhooks to trigger other functions.

Event types and payload structures

Each subscription will send a simple POST message to the subscribed URL containing a JSON object with information about the event. The body of each POST message is succinct, but varies according to the event type. You can access the included URL to learn more about the included resource.

A report starts running

{
  "event": "report_run_started",
  "report_run_url": "https://modeanalytics.com/api/[ORG_TOKEN]/reports/[REPORT_TOKEN]/runs/[RUN_TOKEN]"
}

A database is connected

{
  "event": "new_database_connection",
  "connection_url": "https://modeanalytics.com/api/[ORG_TOKEN]/data_sources/[DATA_SOURCE_TOKEN]"
}

A definition is created

{
  "event": "definition_created",
  "definition_url": "https://modeanalytics.com/api/[ORG_TOKEN]/definitions/[DEFINITION_TOKEN]"
}

A definition is updated

{
  "event": "definition_updated",
  "definition_url": "https://modeanalytics.com/api/[ORG_TOKEN]/definitions/[DEFINITION_TOKEN]"
}

Someone joins your Workspace

{
  "event": "member_joined_organization",
  "member_url": "https://modeanalytics.com/api/[ORG_TOKEN]/memberships/[MEMBERSHIP_TOKEN]?embed[user]=1"
}

Someone was removed from your Workspace

{
  "event": "member_removed_from_organization",
  "member_url": "https://modeanalytics.com/api/[ORG_TOKEN]/memberships/[MEMBERSHIP_TOKEN]?embed[user]=1"
}

A new Report is created

{
  "event": "report_created",
  "report_run_url": "https://modeanalytics.com/api/[ORG_TOKEN]/reports/[REPORT_TOKEN]"
}

A Report finishes running

{
  "event": "report_run_completed",
  "report_run_url": "https://modeanalytics.com/api/[ORG_TOKEN]/reports/[REPORT_TOKEN]/runs/[RUN_TOKEN]"
}

A Report is deleted

{
  "event": "report_deleted",
  "report_name": "[REPORT_NAME]",
  "report_token": "[REPORT_TOKEN]"
}

FAQs

Q: How to set up alerts with Webhooks?

A convenient way to trigger alerts is by utilizing Analyst Studio’s Webhooks feature. This allows you to set up a webhook that sends notifications when a Report or query finishes running, as outlined in this guide.

Additionally, you can review the data returned from the run, and if a specific value exceeds a set threshold, an alert can be sent to Slack. This example Python script demonstrates this process. The logic is located within the post_to_slack.py file, specifically within the report_run_completed_message function. Feel free to modify the logic as necessary for your specific use case.

Was this page helpful?
×