mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
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>
This commit is contained in:
Pepe Cano
GitHub
parent
da66060f75
commit
f1b4678012
@ -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
|
||||
|
||||
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. |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user