Overview

Webhooks let other applications subscribe to be notified when certain events happen in your Mode 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 a Mode report finishes running
• Log usage of your Mode Workspace

When you set up a webhook, Mode 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. Mode'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. If you have ideas for new events you'd like to see in Mode, please let our success team know. You can learn more about what's possible by viewing sample code in our webhooks example repo and refer to Mode's API documentation.

Create and subscribe to a webhook

1. On the top left of Mode 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, Mode will send a test event to the target URL to make sure the response is successful.

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 Mode'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.