From 3189a43fba5d89a92b0fa3fd09785f556f89b758 Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 18:53:43 +0000 Subject: [PATCH 1/6] alerts documentation --- docs/docs/guide/9-alerts.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index 2adbb61f..3a5e8911 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -24,4 +24,34 @@ Consider configuring a "no queries submitted" alert to monitor system health. If ## Alert Mediums -Groundlight supports the following alerts via Email, Text Message (SMS), and Webhooks. +Groundlight supports alerts via Email, Text Message (SMS), and Webhooks. + +### Webhooks + +By setting up a webhook alert for your Groundlight detector, you can integrate Groundlight's computer vision technology with your existing messaging platform, other tech stack, or even a custom application. + +You can either set up an alert using one of our default templates (currently available for Slack, more platforms to come), or build your own. + +#### Custom Templates + +We use Jinja2 to manage and render templates. See the ([Jinja template documentation](https://jinja.palletsprojects.com/en/stable/templates/)) for information on how to build your template. +The template will need to be a valid Jinja template which renders to valid JSON to be used as a payload for your webhook alert. + +We provide a set of variables which you can use to put information about your detector and alert into your template. +The available variables are: + +- `detector_name`: The name of your detector that the alert was triggered on +- `detector_query`: The detector's query. +- `detector_id`: The detector's unique ID +- `confidence_threshold`: The current confidence threshold for the detector. +- `detector_mode`: The detector's mode (binary, count, multiclass, etc). Currently, alerts are only available for binary detectors. +- `image_query_id`: The id of the image query which triggered the alert +- `time_repr`: A human readable string of the time the alert was triggered in UTC. Does not include the date. +- `activation_time`: The time and date the alert was triggered in UTC. +- `condition_repr`: The condition the alert is configured with, put into a human-readable string (eg. " returned a YES answer at "). +- `image_url`: An image URL to acccess the image which triggered the alert. Only available if the alert was configured with `include_image` set to True. + +#### Headers + +Optionally, you can also configure the headers for your webhook alert POST. This is particularly useful if your application requires a specific security token to accept incoming POST requests. +If your application requires headers, you can provide them as a JSON dictionary. If not, you can configure your template and leave the headers blank. \ No newline at end of file From 4046130108b31873a139cc5bdaba492d6cce3a5c Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 18:59:23 +0000 Subject: [PATCH 2/6] wording changes --- docs/docs/guide/9-alerts.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index 3a5e8911..40a1ad6d 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -34,7 +34,7 @@ You can either set up an alert using one of our default templates (currently ava #### Custom Templates -We use Jinja2 to manage and render templates. See the ([Jinja template documentation](https://jinja.palletsprojects.com/en/stable/templates/)) for information on how to build your template. +We use Jinja2 to manage and render templates. See the ([Jinja template documentation](https://jinja.palletsprojects.com/en/stable/templates/)) for information on how to construct your template. The template will need to be a valid Jinja template which renders to valid JSON to be used as a payload for your webhook alert. We provide a set of variables which you can use to put information about your detector and alert into your template. @@ -53,5 +53,5 @@ The available variables are: #### Headers -Optionally, you can also configure the headers for your webhook alert POST. This is particularly useful if your application requires a specific security token to accept incoming POST requests. +Optionally, you can also configure the headers for your webhook alert POST request. This is particularly useful if your application requires a specific security token to be present to accept incoming POST requests. If your application requires headers, you can provide them as a JSON dictionary. If not, you can configure your template and leave the headers blank. \ No newline at end of file From 509cc1454a0f1558c8cd22b631b60c7630ddc904 Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 19:01:53 +0000 Subject: [PATCH 3/6] too many cs --- docs/docs/guide/9-alerts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index 40a1ad6d..0c73ccef 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -49,7 +49,7 @@ The available variables are: - `time_repr`: A human readable string of the time the alert was triggered in UTC. Does not include the date. - `activation_time`: The time and date the alert was triggered in UTC. - `condition_repr`: The condition the alert is configured with, put into a human-readable string (eg. " returned a YES answer at "). -- `image_url`: An image URL to acccess the image which triggered the alert. Only available if the alert was configured with `include_image` set to True. +- `image_url`: An image URL to access the image which triggered the alert. Only available if the alert was configured with `include_image` set to True. #### Headers From c5ff4986d62dc76dbdf58d4704486f7e3d936fa8 Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 13:02:40 -0700 Subject: [PATCH 4/6] Update docs/docs/guide/9-alerts.md Co-authored-by: Tom Faulhaber --- docs/docs/guide/9-alerts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index 0c73ccef..d32daa25 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -30,7 +30,7 @@ Groundlight supports alerts via Email, Text Message (SMS), and Webhooks. By setting up a webhook alert for your Groundlight detector, you can integrate Groundlight's computer vision technology with your existing messaging platform, other tech stack, or even a custom application. -You can either set up an alert using one of our default templates (currently available for Slack, more platforms to come), or build your own. +You can either set up an alert using one of our default templates (currently available for Slack, more platforms to come) or build your own. #### Custom Templates From a0f6178ad842c881313727d76a47c7104b9d7147 Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 13:02:51 -0700 Subject: [PATCH 5/6] Update docs/docs/guide/9-alerts.md Co-authored-by: Tom Faulhaber --- docs/docs/guide/9-alerts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index d32daa25..27b91340 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -40,7 +40,7 @@ The template will need to be a valid Jinja template which renders to valid JSON We provide a set of variables which you can use to put information about your detector and alert into your template. The available variables are: -- `detector_name`: The name of your detector that the alert was triggered on +- `detector_name`: The name of the detector that the alert was triggered on - `detector_query`: The detector's query. - `detector_id`: The detector's unique ID - `confidence_threshold`: The current confidence threshold for the detector. From 920dad35a93098b946a2102f328f5d4513c741f4 Mon Sep 17 00:00:00 2001 From: Francine Wright Date: Tue, 25 Mar 2025 20:12:20 +0000 Subject: [PATCH 6/6] add example --- docs/docs/guide/9-alerts.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/docs/guide/9-alerts.md b/docs/docs/guide/9-alerts.md index 0c73ccef..c54c9ede 100644 --- a/docs/docs/guide/9-alerts.md +++ b/docs/docs/guide/9-alerts.md @@ -51,6 +51,20 @@ The available variables are: - `condition_repr`: The condition the alert is configured with, put into a human-readable string (eg. " returned a YES answer at "). - `image_url`: An image URL to access the image which triggered the alert. Only available if the alert was configured with `include_image` set to True. +For example, the template below could be used as a custom payload to configure a Slack alert which includes a basic message and the triggering image. +``` +"""{ + "text": "Alert activated on Groundlight detector {{ detector_name }} (Query: {{ detector_query }}). Detector {{ condition_repr }} {{ time_repr }}", + "attachments": [ + { + "fallback": "Optional image attachment for the detector alert.", + "image_url": "{{ image_url }}", + "title": "Related Image" + } + ] +}""" +``` + #### Headers Optionally, you can also configure the headers for your webhook alert POST request. This is particularly useful if your application requires a specific security token to be present to accept incoming POST requests.