diff --git a/docs/README.md b/docs/README.md index fa3539ab718328cc7b9eba5a91fe78d9a537a081..5c85f7101e669c5bc7530aee042c15b71661d29a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -180,6 +180,7 @@ Metabase's reference documentation. - [General settings](./configuring-metabase/settings.md) - [Email](./configuring-metabase/email.md) - [Slack](./configuring-metabase/slack.md) +- [Webhooks](./configuring-metabase/webhooks.md) - [Environment variables](./configuring-metabase/environment-variables.md) - [Configuration file](./configuring-metabase/config-file.md) - [Metabase log configuration](./configuring-metabase/log-configuration.md) diff --git a/docs/configuring-metabase/email.md b/docs/configuring-metabase/email.md index d3964f29c0e598d64a8f830b82c199cdf32780bb..572a91c949161792b318ad59204d86f127b04975 100644 --- a/docs/configuring-metabase/email.md +++ b/docs/configuring-metabase/email.md @@ -12,7 +12,8 @@ To edit email settings: 1. Click on the **gear** icon in the upper right. 2. Select **Admin Settings**. -3. From the default **Settings** tab, click on **Email** in the left sidebar. +3. From the default **Settings** tab, click on **Notification channels** in the left sidebar. +4. Select **Email**. ## Metabase Cloud @@ -20,8 +21,8 @@ Metabase Cloud manages an email server for you, so you don't need to set up emai If you like, you can still set up: -- a name for your Cloud email account (from name) -- an email address to recieve email replies (reply-to address) +- A name for your Cloud email account (from name) +- An email address to receive email replies (reply-to address) ## Configuring your email account diff --git a/docs/configuring-metabase/images/payload-chart.png b/docs/configuring-metabase/images/payload-chart.png new file mode 100644 index 0000000000000000000000000000000000000000..3973a2ddbfacfd3d6eefe136576cddb7c16c060f Binary files /dev/null and b/docs/configuring-metabase/images/payload-chart.png differ diff --git a/docs/configuring-metabase/images/table-view.png b/docs/configuring-metabase/images/table-view.png new file mode 100644 index 0000000000000000000000000000000000000000..29d8631b45388975738a563cb03571c0bb5ad63a Binary files /dev/null and b/docs/configuring-metabase/images/table-view.png differ diff --git a/docs/configuring-metabase/slack.md b/docs/configuring-metabase/slack.md index 81d4172973274ca643aede1384fdc468fef42c8a..a683f43f23ff8e0de93f88dfec399bc251c976c2 100644 --- a/docs/configuring-metabase/slack.md +++ b/docs/configuring-metabase/slack.md @@ -12,7 +12,7 @@ If you want to have your [dashboard subscriptions](../dashboards/subscriptions.m For Metabase to post to your Slack channels, you’ll need to create a Slack App and make it available to Metabase. -From any Metabase page, go to **Admin settings** > **Settings** > **Slack**. +From any Metabase page, go to **Admin settings** > **Settings** > **Notification channels** > **Slack**. Click on **Open Slack Apps**. Metabase will open a new browser tab and send you over to the Slack website to create the Slack app. diff --git a/docs/configuring-metabase/start.md b/docs/configuring-metabase/start.md index fb6752dcc29352b69861bc4217f46cb84bb3f445..425483807311af7080346b68df945cd1c21f27bb 100644 --- a/docs/configuring-metabase/start.md +++ b/docs/configuring-metabase/start.md @@ -20,6 +20,10 @@ Set up email for [Alerts](../questions/sharing/alerts.md) and [Dashboard subscri Set up Slack for Alerts and Dashboard subscriptions. +### [Webhooks](./webhooks.md) + +Set up webhooks as notification channels for alerts. + ## [Environment variables](./environment-variables.md) Configure Metabase on launch via environment variables. diff --git a/docs/configuring-metabase/webhooks.md b/docs/configuring-metabase/webhooks.md new file mode 100644 index 0000000000000000000000000000000000000000..9f1689a83b24eaa43d0ca21b718fc540aa464606 --- /dev/null +++ b/docs/configuring-metabase/webhooks.md @@ -0,0 +1,120 @@ +--- +title: Webhooks +--- + +# Webhooks + +Admins can set up webhooks so that people can send [alerts](../questions/sharing/alerts.md) to a particular URL. Which means you can set up an alert to send the results of a question to an endpoint of your choice: to your app, a third-party service, or wherever. + +For now, webhooks are only available for [alerts](../questions/sharing/alerts.md); you can't select a webhook as the recipient of a [dashboard subscription](../dashboards/subscriptions.md). + +## Creating a webhook + +Before you can send an alert to a webhook, an admin will need to create a webhook to target. + +Admins can create a webhook by clicking on the **gear icon** > **Admin settings** > **Notification channels**. In the **Webhooks for alerts**, click **+ Add another**. Metabase will hand you a short form to fill out: + +- **Webhook URL**. Where you want Metabase to send the results of an alert. Must be a valid URL. +- **Give it a name**. You have to name the webhook so that people can pick the right hook when setting up an alert on a question. +- **Description**. You should probably tell people what the hook is for. +- **Authentication method**. See below. + +## Webhook authentication method + +You can specify an auth method for the webhook. + +- **None**: Anything goes. +- **Basic**: Set a username and password. +- **Bearer**: Include a [secret token](https://datatracker.ietf.org/doc/html/rfc6750). +- **API key**: You can add the API key to the Header or as a Query param. Both approaches require a key and value (the API key itself). + +## Webhook payload + +Metabase will send the results of an alert in JSON. The JSON will include some metadata about the question, like the alert's creator and its ID (`null` in the case of test alerts). + +Metabase will send the "attached" visualization as a base64-encoded PNG in the `data` key, under `visualization`. + + + +And the data as seen in the table view, which Metabase will send as a `raw_data`. + + + +Here's an example payload for an alert (we truncated the PNG encoding because it's long and extremely boring): + +```JSON +{ + "type": "alert", + "alert_id": null, + "alert_creator_id": 2666, + "alert_creator_name": "Roberto Bolaño", + "data": { + "type": "question", + "question_id": 108, + "question_name": "Sales", + "question_url": "http://example.com/question/108", + "visualization": "data:image/png;base64,=...LONG_ENCODED_PNG_HERE...", + "raw_data": { + "cols": [ + "CREATED_AT", + "count" + ], + "rows": [ + [ + "2023-09-01T00:00:00Z", + 346 + ], + [ + "2023-10-01T00:00:00Z", + 354 + ], + [ + "2023-11-01T00:00:00Z", + 394 + ], + [ + "2023-12-01T00:00:00Z", + 418 + ], + [ + "2024-01-01T00:00:00Z", + 457 + ], + [ + "2024-02-01T00:00:00Z", + 404 + ], + [ + "2024-03-01T00:00:00Z", + 445 + ], + [ + "2024-04-01T00:00:00Z", + 439 + ], + [ + "2024-05-01T00:00:00Z", + 520 + ], + [ + "2024-06-01T00:00:00Z", + 455 + ], + [ + "2024-07-01T00:00:00Z", + 523 + ], + [ + "2024-08-01T00:00:00Z", + 501 + ] + ] + } + }, + "sent_at": "2024-09-30T20:16:15.76582Z" +} +``` + +## Further reading + +- [Alerts](../questions/sharing/alerts.md) diff --git a/docs/questions/images/get-alerts-about-this.png b/docs/questions/images/get-alerts-about-this.png index c227fc9b406b60896ea4bf0e4a2fea6eca1cf93f..322de387bd27611628f1d0c477701b170cb2fb41 100644 Binary files a/docs/questions/images/get-alerts-about-this.png and b/docs/questions/images/get-alerts-about-this.png differ diff --git a/docs/questions/images/the-wide-world-of-alerts.png b/docs/questions/images/the-wide-world-of-alerts.png new file mode 100644 index 0000000000000000000000000000000000000000..fcf6149fe1466afe8136b81045eb25f82462f357 Binary files /dev/null and b/docs/questions/images/the-wide-world-of-alerts.png differ diff --git a/docs/questions/sharing/alerts.md b/docs/questions/sharing/alerts.md index 73f703dfc6ec5db0a93b84932534e0ca948be567..256b9d6945b9eacc8d4c72b96dbba4b0f2cc1976 100644 --- a/docs/questions/sharing/alerts.md +++ b/docs/questions/sharing/alerts.md @@ -6,40 +6,48 @@ redirect_from: # Alerts -Set up an alert on a question to send the results of questions to people via email or Slack. +Set up an alert to send the results of questions to people via email or Slack, or to a webhook. + + + +Alerts are for questions only. If you instead want to get the results of a dashboard sent to you, check out [dashboard subscriptions](../../dashboards/subscriptions.md). ## Prerequisite for alerts -To start using alerts, an administrator will need to make sure that either [email](../../configuring-metabase/email.md) or [Slack](../../configuring-metabase/slack.md) is set up for your Metabase. +To start using alerts, an administrator will need to have set up at least one of the following notification channels. + +- [Email](../../configuring-metabase/email.md) +- [Slack](../../configuring-metabase/slack.md) +- [Webhooks](../../configuring-metabase/webhooks.md) -## Setting up an alert +## Creating an alert -Go to a question and click on the **bell** icon in the bottom right of the screen. +Save your question, click on the sharing icon in the top-right of the screen, and select **Create alert**. + + ## Types of alerts There are three kinds of things you can get alerted about in Metabase: +- [Results alerts](#results-alerts): when a question returns any result. - [Goal line alerts](#goal-line-alerts) when a time series crosses a goal line. - [Progress bar alerts](#progress-bar-alerts): when a progress bar reaches or goes below its goal. -- [Results alerts](#results-alerts): when a question returns any result. ## Goal line alerts -Goal line alerts are useful when you're doing things like tracking daily active users and you want to know when you reach a certain number of DAU, or when you're tracking orders per week and you want to know whenever the number of orders ever goes below a certain threshold. +_Requires a goal line and a time series._ + +Goal line alerts are useful when you're doing things like tracking daily active users (DAU) and you want to know when you reach a certain number of DAU, or when you're tracking orders per week and you want to know whenever the number of orders ever goes below a certain threshold. To start, you'll need a line, area, or bar chart displaying a number over time. Next, you need to set up a goal line on your chart. Open up the visualization settings by clicking the **gear** icon in the bottom-left. Then click on the **Display** tab, and turn on the **Show goal** setting. Choose a value for your goal (and optionally a label) and click Done. -Save your question, then click on the bell icon in the bottom-right of the screen. - - - -This is where you'll get to choose a few things: +You can choose: -- Whether you want to be alerted when the time series goes above the goal line or when it goes below it. -- Whether you only wanted to be alerted every time this happens or only the first time. +- Whether you want Metabase to alert you when the time series goes above the goal line or when it goes below the goal line. +- Whether you want Metabase to alert you every time the time series crosses a goal line, or only the first time it crosses the goal line. - How often you want Metabase to check to see if the goal line has been crossed.  @@ -48,6 +56,8 @@ Click Done, and your alert will be all set up! You'll get an email confirmation, ## Progress bar alerts +_Requires a goal line and the progress bar visualization._ + Setting up this kind of alert is really similar to setting up a goal line alert. First, create a question that returns a single number as its result, then choose the Progress Bar chart type from the Visualization menu. Open the settings menu to select a goal value, click Done, then save your question. Next, click the bell icon in the bottom-right and you'll see that same screen of options for when you want to get alerts about this progress bar. @@ -56,11 +66,11 @@ Next, click the bell icon in the bottom-right and you'll see that same screen of Lastly, you can get an alert when one of your saved questions returns _any_ result. This kind of alert is the most useful if you have a question that doesn't _usually_ return any results, but you just want to know when it _does_ return results. -For example, you might have a table called `Reviews`, and you want to know any time a customer leaves a bad review, which you consider to be anything below three stars. To set up an alert for this situation, you'd go and create a raw data question (i.e., a question that returns a list of reviews), and add a filter to only include results with one or two stars. +For example, you might have a table called `Reviews`, and you want to know any time a customer leaves a bad review, which you consider to be anything below three stars. To set up an alert for this situation, you'd go and create a raw data question (i.e., a question that returns a list of reviews), and add a filter to only include results with fewer than three stars. You probably don't want to be alerted about all the bad reviews you've _ever_ gotten, but just recent ones. So you can add a filter to only include results from yesterday or today, depending on how often you want to check for these bad reviews. At this point, when you check the results of this question, it probably won't return any results, which is a good thing. -Save the question, the click on the bell icon in the bottom-right of the screen, and select how often you want Metabase to check this question for results. That's it! +Save the question, create an alert, and select how often you want Metabase to check this question for results. That's it! ## Editing and deleting alerts @@ -73,7 +83,7 @@ Admins get special privileges with alerts. ### Everyone -- Everyone can edit alerts that they've set up (but not alerts set up by other people). +- Everyone can edit alerts that they've personally set up (but not alerts set up by other people). - Everyone can view and unsubscribe from all alerts they receive by clicking on the **gear** icon in the upper right and navigating to **Account settings** > **Notifications**. ## Avoid changing the name of the alerted channel in Slack diff --git a/docs/questions/sharing/image.png b/docs/questions/sharing/image.png new file mode 100644 index 0000000000000000000000000000000000000000..b2e72d6d85f39bf8c1f848ff4c7cfb3b48fda608 Binary files /dev/null and b/docs/questions/sharing/image.png differ