apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[release-11.5.2] Alerting docs: update `Configure Webhook notifications` (#100708)

Browse Source 
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 <matthew.jacobson@grafana.com>

* Update docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md

Co-authored-by: Matthew Jacobson <matthew.jacobson@grafana.com>

* 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 <matthew.jacobson@grafana.com>
(cherry picked from commit f1b4678012)

Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com>
pull/100739/head
grafana-delivery-bot[bot] 4 months ago committed by GitHub
parent b774d0d569
commit 72e8b57597
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 112 additions and 71 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 183
      docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md

183
docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md
Unescape View File

@ -28,13 +28,83 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/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/<GRAFANA_VERSION>/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
Use the webhook integration in contact points to send alert notifications to your webhook.
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
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.
| Option | Description |
| ------ | ---------------- |
| URL | The Webhook URL. |
## Webhook JSON payload
#### 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 |
{{< 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**.
The Alert object represents an alert included in the notification group, as provided by the [`alerts` field](#body).
| 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. |

Write Preview
Loading…
Cancel
Save