From 72e8b57597def83a1765d06d5c07f919ebd6623d Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Fri, 14 Feb 2025 11:20:14 +0100 Subject: [PATCH] [release-11.5.2] Alerting docs: update `Configure Webhook notifications` (#100708) Alerting docs: update `Configure Webhook notifications` (#100650) * Alerting docs: update `Configure Webhook notifications` * fix typo * fix typo * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md Co-authored-by: Matthew Jacobson * Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md Co-authored-by: Matthew Jacobson * fix typo * Add `Note` to configure either HTTP Basic Authentication or the Authorization request header * Use `inline` format for JSON keys --------- Co-authored-by: Matthew Jacobson (cherry picked from commit f1b4678012ca5626c7e8acd9a47f880f3f51a4c6) Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> --- .../integrations/webhook-notifier.md | 181 +++++++++++------- 1 file changed, 111 insertions(+), 70 deletions(-) diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md index 6562b948095..1a7598891a1 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md @@ -28,13 +28,83 @@ refs: destination: /docs/grafana//alerting/configure-notifications/template-notifications/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/ + configure-contact-points: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/ --- -# Configure the webhook notifier for Alerting +# Configure webhook notifications -The webhook notification is a simple way to send information about a state change over HTTP to a custom endpoint. Using this notification you could integrate Grafana into a system of your choosing. +Use the webhook integration in contact points to send alert notifications to your webhook. -## Webhook JSON payload +The webhook integration is a flexible way to integrate alerts into your system. When a notification is triggered, it sends a JSON request with alert details and additional data to the webhook endpoint. + +## Configure webhook for a contact point + +To create a contact point with webhook integration, complete the following steps. + +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +1. Click **+ Add contact point**. +1. Enter a name for the contact point. +1. From the **Integration** list, select **Webhook**. +1. In the **URL** field, copy in your Webhook URL. +1. (Optional) Configure [additional settings](#settings). +1. Click **Save contact point**. + +For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points). + +## Webhook settings + +| Option | Description | +| ------ | ---------------- | +| URL | The Webhook URL. | + +#### Optional settings + +| Option | Description | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| HTTP Method | Specifies the HTTP method to use: `POST` or `PUT`. | +| Basic Authentication Username | Username for HTTP Basic Authentication. | +| Basic Authentication Password | Password for HTTP Basic Authentication. | +| Authentication Header Scheme | Scheme for the `Authorization` Request Header. Default is `Bearer`. | +| Authentication Header Credentials | Credentials for the `Authorization` Request header. | +| Max Alerts | Maximum number of alerts to include in a notification. Any alerts exceeding this limit are ignored. `0` means no limit. | +| TLS | TLS configuration options, including CA certificate, client certificate, and client key. | + +{{< admonition type="note" >}} + +You can configure either HTTP Basic Authentication or the Authorization request header, but not both. + +{{< /admonition >}} + +#### Optional settings using templates + +Use the following settings to include custom data within the [JSON payload](#body). Both options support using [notification templates](ref:notification-templates). + +| Option | Description | +| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Title | Sends the value as a string in the `title` field of the [JSON payload](#body). Supports [notification templates](ref:notification-templates). | +| Message | Sends the value as a string in the `message` field of the [JSON payload](#body). Supports [notification templates](ref:notification-templates). | + +{{< admonition type="note" >}} +You can customize the `title` and `message` options to include custom messages and notification data using notification templates. These fields are always sent as strings in the JSON payload. + +However, you cannot customize the webhook data structure, such as adding or changing other JSON fields and HTTP headers, or sending data in a different format like XML. + +If you need to format these fields as JSON or modify other webhook request options, consider sending webhook notifications to a proxy server that adjusts the webhook request before forwarding it to the final destination. +{{< /admonition >}} + +#### Optional notification settings + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------- | +| Disable resolved message | Enable this option to prevent notifications when an alert resolves. | + +## JSON payload + +The following example shows the payload of a webhook notification containing information about two firing alerts: ```json { @@ -106,76 +176,47 @@ The webhook notification is a simple way to send information about a state chang } ``` -## Webhook fields - ### Body -| Key | Type | Description | -| ----------------- | ------------------------- | ------------------------------------------------------------------------------- | -| receiver | string | Name of the webhook | -| status | string | Current status of the alert, `firing` or `resolved` | -| orgId | number | ID of the organization related to the payload | -| alerts | array of [alerts](#alert) | Alerts that are triggering | -| groupLabels | object | Labels that are used for grouping, map of string keys to string values | -| commonLabels | object | Labels that all alarms have in common, map of string keys to string values | -| commonAnnotations | object | Annotations that all alarms have in common, map of string keys to string values | -| externalURL | string | External URL to the Grafana instance sending this webhook | -| version | string | Version of the payload | -| groupKey | string | Key that is used for grouping | -| truncatedAlerts | number | Number of alerts that were truncated | -| title | string | Custom title | -| state | string | State of the alert group (either `alerting` or `ok`) | -| message | string | Custom message | +The JSON payload of webhook notifications includes the following key-value pairs: + +| Key | Type | Description | +| ------------------- | ------------------------- | -------------------------------------------------------------------------------- | +| `receiver` | string | Name of the contact point. | +| `status` | string | Current status of the alert, `firing` or `resolved`. | +| `orgId` | number | ID of the organization related to the payload. | +| `alerts` | array of [alerts](#alert) | Alerts that are triggering. | +| `groupLabels` | object | Labels that are used for grouping, map of string keys to string values. | +| `commonLabels` | object | Labels that all alarms have in common, map of string keys to string values. | +| `commonAnnotations` | object | Annotations that all alarms have in common, map of string keys to string values. | +| `externalURL` | string | External URL to the Grafana instance sending this webhook. | +| `version` | string | Version of the payload structure. | +| `groupKey` | string | Key that is used for grouping. | +| `truncatedAlerts` | number | Number of alerts that were truncated. | +| `state` | string | State of the alert group (either `alerting` or `ok`). | + +The following key-value pairs are also included in the JSON payload and can be configured in the [webhook settings using notification templates](#optional-settings-using-templates). + +| Key | Type | Description | +| --------- | ------ | -------------------------------------------------------------------------------------------------------------------- | +| `title` | string | Custom title. Configurable in [webhook settings using notification templates](#optional-settings-using-templates). | +| `message` | string | Custom message. Configurable in [webhook settings using notification templates](#optional-settings-using-templates). | ### Alert -| Key | Type | Description | -| ------------ | ------ | ---------------------------------------------------------------------------------- | -| status | string | Current status of the alert, `firing` or `resolved` | -| labels | object | Labels that are part of this alert, map of string keys to string values | -| annotations | object | Annotations that are part of this alert, map of string keys to string values | -| startsAt | string | Start time of the alert | -| endsAt | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z` | -| values | object | Values that triggered the current status | -| generatorURL | string | URL of the alert rule in the Grafana UI | -| fingerprint | string | The labels fingerprint, alarms with the same labels will have the same fingerprint | -| silenceURL | string | URL to silence the alert rule in the Grafana UI | -| dashboardURL | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation | -| panelURL | string | A link to the panel if the alert has a Panel ID annotation | -| imageURL | string | URL of a screenshot of a panel assigned to the rule that created this notification | +The Alert object represents an alert included in the notification group, as provided by the [`alerts` field](#body). -{{< admonition type="note" >}} - -You can customize the `title` and `message` fields using [notification templates](ref:notification-templates). - -However, you cannot customize webhook data structure or format, including JSON fields or sending data in XML, nor can you change the webhook HTTP headers. - -{{< /admonition >}} - -## Procedure - -To create your Webhook integration in Grafana Alerting, complete the following steps. - -1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. -1. Click **+ Add contact point**. -1. Enter a contact point name. -1. From the Integration list, select **Webhook**. -1. In the **URL** field, copy in your Webhook URL. -1. Click **Test** to check that your integration works. - - ** For Grafana Alertmanager only.** - -1. Click **Save contact point**. - -## Next steps - -The Webhook contact point is ready to receive alert notifications. - -To add this contact point to your alert, complete the following steps. - -1. In Grafana, navigate to **Alerting** > **Alert rules**. -1. Edit or create a new alert rule. -1. Scroll down to the **Configure labels and notifications** section. -1. Under Notifications, click **Select contact point**. -1. From the drop-down menu, select the previously created contact point. -1. **Click Save rule and exit**. +| Key | Type | Description | +| -------------- | ------ | ----------------------------------------------------------------------------------- | +| `status` | string | Current status of the alert, `firing` or `resolved`. | +| `labels` | object | Labels that are part of this alert, map of string keys to string values. | +| `annotations` | object | Annotations that are part of this alert, map of string keys to string values. | +| `startsAt` | string | Start time of the alert. | +| `endsAt` | string | End time of the alert, default value when not resolved is `0001-01-01T00:00:00Z`. | +| `values` | object | Values that triggered the current status. | +| `generatorURL` | string | URL of the alert rule in the Grafana UI. | +| `fingerprint` | string | The labels fingerprint, alarms with the same labels will have the same fingerprint. | +| `silenceURL` | string | URL to silence the alert rule in the Grafana UI. | +| `dashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation. | +| `panelURL` | string | A link to the panel if the alert has a Panel ID annotation. | +| `imageURL` | string | URL of a screenshot of a panel assigned to the rule that created this notification. |