docs - webhooks draft (#48239)

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)

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
 

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.
 

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.

docs/configuring-metabase/webhooks.md

+---
+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`.
+
+![The encoded PNG chart](./images/payload-chart.png)
+
+And the data as seen in the table view, which Metabase will send as a `raw_data`.
+
+![Results as table view](./images/table-view.png)
+
+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)

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.
+
+![The wide world of alerts](../images/the-wide-world-of-alerts.png)
+
+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**.
+
+![Get alerts](../images/get-alerts-about-this.png)
 
 ## 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.
-
-![Get alerts](../images/get-alerts-about-this.png)
-
-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.
 
 ![Goal line alert options](../images/goal-line-options.png)
@@ -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