Outgoing webhooks 2 documentation (#1844)
Documentation for new outgoing webhooks. --------- Co-authored-by: Vadim Stepanov <vadimkerr@gmail.com>
This commit is contained in:
Michael Derynck
GitHub
parent
4553e49b7a
commit
0bef6efde6
4 changed files with 820 additions and 36 deletions
|
|
@ -8,6 +8,7 @@ keywords:
|
|||
- Alerts
|
||||
- Notifications
|
||||
- on-call
|
||||
- webhooks
|
||||
- Jira
|
||||
title: Jira
|
||||
weight: 500
|
||||
|
|
@ -50,6 +51,126 @@ Grafana OnCall provides grouping, auto-acknowledge and auto-resolve logic for th
|
|||
|
||||
To customize this behaviour, consider modifying alert templates in integration settings.
|
||||
|
||||
## Configuring Grafana OnCall to send data to Jira
|
||||
|
||||
Grafana OnCall can automatically create and resolve issues in Jira via [outgoing webhooks]({{< relref "_index.md" >}}).
|
||||
This guide provides example webhook configurations for common use cases, as well as information on how to set up a user in Jira to be used by Grafana OnCall.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Create a new user in Jira to be used by Grafana OnCall. [Obtain an API token for the user](https://id.atlassian.com/manage-profile/security/api-tokens),
|
||||
these credentials will be used to communicate with Jira REST API.
|
||||
2. Make sure the user has appropriate permissions to create and update issues in Jira.
|
||||
|
||||
### Create issues in Jira
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically create
|
||||
issues in Jira from Grafana OnCall alert groups.
|
||||
|
||||
Create a new Outgoing Webhook in Grafana OnCall, and configure it as follows:
|
||||
|
||||
- Trigger type: `Alert Group Created`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `POST`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.atlassian.net/rest/api/2/issue
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your Jira instance.
|
||||
|
||||
- Username: Email of the [Jira user](#prerequisites)
|
||||
|
||||
- Password: API token of the [Jira user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"project": {
|
||||
"key": "<PROJECT_KEY>"
|
||||
},
|
||||
"issuetype": {
|
||||
"name": "[System] Incident"
|
||||
},
|
||||
"summary": "{{alert_group.title}}",
|
||||
"description": "This issue is created automatically by Grafana OnCall. Alert group {{alert_group.id}}: {{alert_group.permalinks.web}}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `<PROJECT_KEY>` with the key of the project in Jira.
|
||||
|
||||
>**Note**: You might want to use a different `issuetype.name` depending on your Jira instance configuration and use case.
|
||||
|
||||
### Resolve issues in Jira
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically resolve
|
||||
issues in Jira when an alert group is resolved in Grafana OnCall.
|
||||
|
||||
- Trigger type: `Resolved`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `POST`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.atlassian.net/rest/api/2/issue/{{responses.<WEBHOOK_ID>.key}}/transitions
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your Jira instance, and `<WEBHOOK_ID>` with the ID of the [webhook used for creating issues](#create-issues-in-jira).
|
||||
|
||||
- Username: Email of the [Jira user](#prerequisites)
|
||||
|
||||
- Password: API token of the [Jira user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"transition": {
|
||||
"id": "<TRANSITION_ID>"
|
||||
},
|
||||
"fields": {
|
||||
"resolution": {
|
||||
"name": "Done"
|
||||
}
|
||||
},
|
||||
"update": {
|
||||
"comment": [
|
||||
{
|
||||
"add": {
|
||||
"body": "Resolved by Grafana OnCall.",
|
||||
"public": false
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Replace `<TRANSITION_ID>` with the ID of the transition specific to your Jira instance.
|
||||
See [here](https://community.atlassian.com/t5/Jira-questions/How-to-fine-transition-ID-of-JIRA/qaq-p/1207483#M385834)
|
||||
for more info on how to find the transition ID in Jira UI, or use the
|
||||
[REST API endpoint](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get)
|
||||
to get the list of available transitions.
|
||||
|
||||
### Advanced usage
|
||||
|
||||
The examples above describe how to create outgoing webhooks in Grafana OnCall that will allow to automatically create and resolve issues in Jira.
|
||||
|
||||
Consider modifying example templates to fit your use case (e.g. to include more information on alert groups).
|
||||
Refer to [outgoing webhooks documentation]({{< relref "_index.md" >}}) for more information on available template variables and webhook configuration.
|
||||
|
||||
For more information on Jira REST API, refer to [Jira REST API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues).
|
||||
|
||||
{{% docs/reference %}}
|
||||
[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
|
||||
[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
|
||||
|
|
|
|||
140
docs/sources/integrations/servicenow/index.md
Normal file
140
docs/sources/integrations/servicenow/index.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
aliases:
|
||||
- servicenow/
|
||||
- /docs/oncall/latest/integrations/available-integrations/configure-servicenow/
|
||||
canonical: https://grafana.com/docs/oncall/latest/integrations/available-integrations/configure-servicenow/
|
||||
keywords:
|
||||
- Grafana Cloud
|
||||
- Alerts
|
||||
- Notifications
|
||||
- on-call
|
||||
- webhooks
|
||||
- ServiceNow
|
||||
title: ServiceNow
|
||||
weight: 500
|
||||
---
|
||||
|
||||
# Integrate Grafana OnCall with ServiceNow
|
||||
|
||||
Grafana OnCall can automatically create, assign and resolve incidents in ServiceNow via [outgoing webhooks]({{< relref "_index.md" >}}).
|
||||
This guide provides example webhook configurations for common use cases, as well as information on how to set up a user in ServiceNow to be used by Grafana OnCall.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Create a new user in ServiceNow to be used by Grafana OnCall. Obtain the username and password for the user,
|
||||
these credentials will be used to communicate with ServiceNow REST API.
|
||||
2. Make sure the user has appropriate permissions to create and update incidents in ServiceNow. By default, the user will need to have the `sn_incident_write` role.
|
||||
|
||||
## Create incidents in ServiceNow
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically create
|
||||
incidents in ServiceNow from Grafana OnCall alert groups.
|
||||
|
||||
Create a new Outgoing Webhook in Grafana OnCall, and configure it as follows:
|
||||
|
||||
- Trigger type: `Alert Group Created`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `POST`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.service-now.com/api/now/table/incident
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your ServiceNow instance.
|
||||
|
||||
- Username: Username of the [ServiceNow user](#prerequisites)
|
||||
|
||||
- Password: Password of the [ServiceNow user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"short_description": "{{alert_group.title}}",
|
||||
"description": "This incident is created automatically by Grafana OnCall.",
|
||||
"work_notes": "Grafana OnCall alert group: [code]<a target='_blank' href='{{alert_group.permalinks.web}}'>{{alert_group.id}}</a>[/code]",
|
||||
"category": "Software"
|
||||
}
|
||||
```
|
||||
|
||||
## Assign incidents in ServiceNow
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically assign incidents in ServiceNow.
|
||||
The assignment will be performed when an alert group is acknowledged in Grafana OnCall.
|
||||
|
||||
- Trigger type: `Acknowledged`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `PUT`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.service-now.com/api/now/table/incident/{{responses.<WEBHOOK_ID>.result.sys_id}}
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your ServiceNow instance, and `<WEBHOOK_ID>` with the ID of the [webhook used for creating incidents](#create-incidents-in-servicenow).
|
||||
|
||||
- Username: Username of the [ServiceNow user](#prerequisites)
|
||||
|
||||
- Password: Password of the [ServiceNow user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"assigned_to": "{{user.email}}"
|
||||
}
|
||||
```
|
||||
|
||||
>**Note**: The incident will be assigned to the user that acknowledged the alert group in Grafana OnCall.
|
||||
The assignment will fail if the user email does not exist in ServiceNow.
|
||||
|
||||
## Resolve incidents in ServiceNow
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically close
|
||||
incidents in ServiceNow when an alert group is resolved in Grafana OnCall.
|
||||
|
||||
- Trigger type: `Resolved`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `PUT`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.service-now.com/api/now/table/incident/{{responses.<WEBHOOK_ID>.result.sys_id}}
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your ServiceNow instance, and `<WEBHOOK_ID>` with the ID of the [webhook used for creating incidents](#create-incidents-in-servicenow).
|
||||
|
||||
- Username: Username of the [ServiceNow user](#prerequisites)
|
||||
|
||||
- Password: Password of the [ServiceNow user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"state": 6,
|
||||
"close_code": "Resolved by caller",
|
||||
"close_notes": "Resolved by Grafana OnCall."
|
||||
}
|
||||
```
|
||||
|
||||
>**Note**: Values for fields `state` and `close_code` may be different for your ServiceNow instance, please check and update the values accordingly.
|
||||
|
||||
## Advanced usage
|
||||
|
||||
The examples above describe how to create outgoing webhooks in Grafana OnCall that will allow to automatically create, assign and resolve incidents in ServiceNow.
|
||||
|
||||
Consider modifying example templates to fit your use case (e.g. to include more information on alert groups).
|
||||
Refer to [outgoing webhooks documentation]({{< relref "_index.md" >}}) for more information on available template variables and webhook configuration.
|
||||
|
||||
For more information on ServiceNow REST API, refer to [ServiceNow REST API documentation](https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest).
|
||||
|
|
@ -8,6 +8,7 @@ keywords:
|
|||
- Alerts
|
||||
- Notifications
|
||||
- on-call
|
||||
- webhooks
|
||||
- Zendesk
|
||||
title: Zendesk
|
||||
weight: 500
|
||||
|
|
@ -65,6 +66,103 @@ Grafana OnCall provides grouping, auto-acknowledge and auto-resolve logic for th
|
|||
|
||||
To customize this behaviour, consider modifying alert templates in integration settings.
|
||||
|
||||
## Configuring Grafana OnCall to send data to Zendesk
|
||||
|
||||
Grafana OnCall can automatically create and resolve tickets in Zendesk via [outgoing webhooks]({{< relref "_index.md" >}}).
|
||||
This guide provides example webhook configurations for common use cases, as well as information on how to set up a user in Zendesk to be used by Grafana OnCall.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Create a new user in Zendesk to be used by Grafana OnCall.
|
||||
[Obtain an API token for the user](https://support.zendesk.com/hc/en-us/articles/4408889192858-Generating-a-new-API-token),
|
||||
these credentials will be used to communicate with Zendesk API.
|
||||
2. Make sure the user has appropriate permissions to create and update tickets in Zendesk.
|
||||
|
||||
### Create tickets in Zendesk
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically create
|
||||
tickets in Zendesk from Grafana OnCall alert groups.
|
||||
|
||||
Create a new Outgoing Webhook in Grafana OnCall, and configure it as follows:
|
||||
|
||||
- Trigger type: `Alert Group Created`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `POST`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.zendesk.com/api/v2/tickets
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your Zendesk instance.
|
||||
|
||||
- Username: Username of the [Zendesk user](#prerequisites), followed by `/token` (e.g. `user@example.com/token`)
|
||||
|
||||
- Password: API token of the [Zendesk user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"ticket": {
|
||||
"type": "incident",
|
||||
"subject": "{{alert_group.title}}",
|
||||
"comment": {
|
||||
"body": "This ticket is created automatically by Grafana OnCall. Alert group {{alert_group.id}}: {{alert_group.permalinks.web}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Resolve tickets in Zendesk
|
||||
|
||||
The steps below describe how to create an outgoing webhook in Grafana OnCall that will allow to automatically resolve
|
||||
tickets in Zendesk when an alert group is resolved in Grafana OnCall.
|
||||
|
||||
- Trigger type: `Resolved`
|
||||
|
||||
- Integrations: Select integrations that will trigger the webhook
|
||||
|
||||
- HTTP method: `PUT`
|
||||
|
||||
- Webhook URL:
|
||||
|
||||
```text
|
||||
https://<INSTANCE>.zendesk.com/api/v2/tickets/{{responses.<WEBHOOK_ID>.ticket.id}}
|
||||
```
|
||||
|
||||
Replace `<INSTANCE>` with your Zendesk instance, and `<WEBHOOK_ID>` with the ID of the [webhook used for creating tickets](#create-tickets-in-zendesk).
|
||||
|
||||
- Username: Username of the [Zendesk user](#prerequisites), followed by `/token` (e.g. `user@example.com/token`)
|
||||
|
||||
- Password: API token of the [Zendesk user](#prerequisites)
|
||||
|
||||
Use the following JSON template as webhook data:
|
||||
|
||||
```json
|
||||
{
|
||||
"ticket": {
|
||||
"status": "solved",
|
||||
"comment": {
|
||||
"body": "Resolved by Grafana OnCall.",
|
||||
"public": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced usage
|
||||
|
||||
The examples above describe how to create outgoing webhooks in Grafana OnCall that will allow to automatically create and resolve tickets in Zendesk.
|
||||
|
||||
Consider modifying example templates to fit your use case (e.g. to include more information on alert groups).
|
||||
Refer to [outgoing webhooks documentation]({{< relref "_index.md" >}}) for more information on available template variables and webhook configuration.
|
||||
|
||||
For more information on Zendesk API, refer to [Zendesk API documentation](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/).
|
||||
|
||||
{{% docs/reference %}}
|
||||
[user-and-team-management]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/user-and-team-management"
|
||||
[user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management"
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
aliases:
|
||||
- ../outgoing-webhooks/
|
||||
- ../integrations/configure-outgoing-webhooks/
|
||||
- /docs/oncall/latest/outgoing-webhooks/
|
||||
canonical: https://grafana.com/docs/oncall/latest/outgoing-webhooks/
|
||||
keywords:
|
||||
- Grafana Cloud
|
||||
|
|
@ -9,54 +10,478 @@ keywords:
|
|||
- on-call
|
||||
- amixr
|
||||
- webhooks
|
||||
title: Outgoing Webhooks
|
||||
weight: 900
|
||||
title: Configure outgoing webhooks for Grafana OnCall
|
||||
weight: 500
|
||||
---
|
||||
|
||||
# Configure outgoing webhooks for Grafana OnCall
|
||||
|
||||
Outgoing webhooks allow you to send alert details to a specified URL from Grafana OnCall. Once an outgoing webhook is
|
||||
configured, you can use it as a notification method in escalation chains.
|
||||
Outgoing webhooks are used by Grafana OnCall to send data to a URL in a flexible way. These webhooks can be
|
||||
triggered from a variety of event types and make use of Jinja2 to transform data into the format required at
|
||||
the destination URL. Each outgoing webhook receives contextual data when executed which can be processed by
|
||||
Jinja2 templates to customize the request being sent.
|
||||
|
||||
To automatically send alert data to a destination URL via outgoing webhook:
|
||||
## Creating an outgoing webhook
|
||||
|
||||
1. In Grafana OnCall, navigate to **Outgoing Webhooks** and click **+ Create**.
|
||||
This is also the place to edit and delete existing outgoing webhooks.
|
||||
2. Provide a name for your outgoing webhook and enter the destination URL.
|
||||
3. If the destination requires authentication, enter your credentials.
|
||||
You can enter a username and password (HTTP) or an authorization header formatted in JSON.
|
||||
4. Configure the webhook payload in the **Data** field.
|
||||
5. Click **Create Webhook**.
|
||||
To create an outgoing webhook navigate to **Outgoing Webhooks** and click **+ Create**. On this screen outgoing
|
||||
webhooks can be viewed, edited and deleted. To create the outgoing webhook populate the required fields and
|
||||
click **Create Webhook**
|
||||
|
||||
The format you use to call the variables must match the structure of how the fields are nested in the alert payload.
|
||||
The **Data** field can use the following four variables to auto-populate the webhook payload with information about
|
||||
the first alert in the alert group:
|
||||
### Outgoing webhook fields
|
||||
|
||||
- `{{ alert_payload }}`
|
||||
- `{{ alert_group_id }}`
|
||||
The outgoing webhook is defined by the following fields. For more information about template usage
|
||||
see [Outgoing webhook templates)](#outgoing-webhook-templates) section.
|
||||
|
||||
`alert_payload` is always the first level of any variable you want to call.
|
||||
#### ID
|
||||
|
||||
The following is an example of an entry in the **Data** field that would return an alert name and description.
|
||||
This field is generated after an outgoing webhook has been created. It is used to reference the responses of
|
||||
other webhooks, see [Advanced Usage - Using response data](#using-response-data) for more details.
|
||||
|
||||
{
|
||||
"name": "{{ alert_payload.labels.alertname }}",
|
||||
"message": "{{ alert_payload.annotations.description }}"
|
||||
#### Name
|
||||
|
||||
Display name of the outgoing webhook.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ✔️ | ❌ | _Empty_ |
|
||||
|
||||
#### Enabled
|
||||
|
||||
Controls whether the outgoing webhook will trigger or is ignored.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ✔️ | ❌ | _True_ |
|
||||
|
||||
#### Assign to Team
|
||||
|
||||
Sets which team owns the outgoing webhook for filtering and visibility.
|
||||
This setting does not restrict outgoing webhook execution to events from the selected team.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _Empty_ |
|
||||
|
||||
#### Trigger Type
|
||||
|
||||
The type of event that will cause this outgoing webhook to execute. The types of triggers are:
|
||||
|
||||
- [Escalation Step](#escalation-step)
|
||||
- [Alert Group Created](#alert-group-created)
|
||||
- [Acknowledged](#acknowledged)
|
||||
- [Resolved](#resolved)
|
||||
- [Silenced](#silenced)
|
||||
- [Unsilenced](#unsilenced)
|
||||
- [Unresolved](#unresolved)
|
||||
- [Unacknowledged](#acknowledged)
|
||||
|
||||
For more details about types of triggers see [Event types](#event-types)
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ✔️ | ❌ | _None_ |
|
||||
|
||||
#### HTTP Method
|
||||
|
||||
The HTTP method used in the request made by the outgoing webhook. This should match what is required by the URL
|
||||
you are sending to.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ✔️ | ❌ | _POST_ |
|
||||
|
||||
#### Integrations
|
||||
|
||||
Restricts the outgoing webhook to only trigger if the event came from a selected integration.
|
||||
If no integrations are selected the outgoing webhook will trigger for any integration.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _None_ |
|
||||
|
||||
#### Webhook URL
|
||||
|
||||
The destination URL the outgoing webhook will make a request to. This must be a FQDN.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ✔️ | ✔️ | _Empty_ |
|
||||
|
||||
#### Webhook Headers
|
||||
|
||||
Headers to add to the outgoing webhook request.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ✔️ | _Empty_ |
|
||||
|
||||
#### Username
|
||||
|
||||
Username to use when making the outgoing webhook request.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _Empty_ |
|
||||
|
||||
#### Password
|
||||
|
||||
Password to use when making the outgoing webhook request.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _Empty_ |
|
||||
|
||||
#### Authorization Header
|
||||
|
||||
Authorization header to use when making the outgoing webhook request.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _None_ |
|
||||
|
||||
#### Trigger Template
|
||||
|
||||
A template used to dynamically determine whether the webhook should execute based on the content of the payload.
|
||||
If the template evaluates to Empty, True or 1 the webhook will execute.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ✔️ | _Empty_ |
|
||||
|
||||
#### Data
|
||||
|
||||
The main body of the request to be sent by the outgoing webhook.
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ✔️ | _Empty_ |
|
||||
|
||||
#### Forward All
|
||||
|
||||
Toggle to send the entire webhook payload instead of using the values in the **Data** field
|
||||
|
||||
| Required | [Template Accepted](#outgoing-webhook-templates) | Default Value |
|
||||
|:--------:|:------------------------------------------------:|:-------------:|
|
||||
| ❌ | ❌ | _False_ |
|
||||
|
||||
## Outgoing webhook templates
|
||||
|
||||
The fields that accept a Jinja2 template in outgoing webhooks are able to process data to customize the output.
|
||||
The following is an example of the data available to access from a template. Some data depending on the timing
|
||||
of the webhook and the triggering event may not always be available,
|
||||
see [field descriptions](#outgoing-webhook-data-fields) specific details. The format you use to call the variables
|
||||
must match the structure of how the fields are nested in the data.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": {
|
||||
"type": "resolve",
|
||||
"time": "2023-04-19T21:59:21.714058+00:00"
|
||||
},
|
||||
"user": {
|
||||
"id": "UVMX6YI9VY9PV",
|
||||
"username": "admin",
|
||||
"email": "admin@localhost"
|
||||
},
|
||||
"alert_group": {
|
||||
"id": "I6HNZGUFG4K11",
|
||||
"integration_id": "CZ7URAT4V3QF2",
|
||||
"route_id": "RKHXJKVZYYVST",
|
||||
"alerts_count": 1,
|
||||
"state": "resolved",
|
||||
"created_at": "2023-04-19T21:53:48.231148Z",
|
||||
"resolved_at": "2023-04-19T21:59:21.714058Z",
|
||||
"acknowledged_at": "2023-04-19T21:54:39.029347Z",
|
||||
"title": "Incident",
|
||||
"permalinks": {
|
||||
"slack": null,
|
||||
"telegram": null,
|
||||
"web": "https://**********.grafana.net/a/grafana-oncall-app/alert-groups/I6HNZGUFG4K11"
|
||||
}
|
||||
|
||||
The following is an example would return an alert name and the alert's labels.
|
||||
|
||||
{
|
||||
"alertname" : "{{ alert_payload.labels.alertname }}",
|
||||
"labels" : "{{ alert_payload.labels }}"
|
||||
},
|
||||
"alert_group_id": "I6HNZGUFG4K11",
|
||||
"alert_payload": {
|
||||
"endsAt": "0001-01-01T00:00:00Z",
|
||||
"labels": {
|
||||
"region": "eu-1",
|
||||
"alertname": "TestAlert"
|
||||
},
|
||||
"status": "firing",
|
||||
"startsAt": "2018-12-25T15:47:47.377363608Z",
|
||||
"amixr_demo": true,
|
||||
"annotations": {
|
||||
"description": "This alert was sent by user for the demonstration purposes"
|
||||
},
|
||||
"generatorURL": ""
|
||||
},
|
||||
"integration": {
|
||||
"id": "CZ7URAT4V3QF2",
|
||||
"type": "webhook",
|
||||
"name": "Main Integration - Webhook",
|
||||
"team": "Webhooks Demo"
|
||||
},
|
||||
"notified_users": [],
|
||||
"users_to_be_notified": [],
|
||||
"responses": {
|
||||
"WHP936BM1GPVHQ": {
|
||||
"id": "7Qw7TbPmzppRnhLvK3AdkQ",
|
||||
"created_at": "15:53:50",
|
||||
"status": "new",
|
||||
"content": {
|
||||
"message": "Ticket created!",
|
||||
"region": "eu"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
By default, this will return labels in a list format. If you'd like your labels to be sent in formatted JSON, please use `| tojson()` in your data. For example:
|
||||
### Outgoing webhook data fields
|
||||
|
||||
{
|
||||
"alertname" : "{{ alert_payload.labels.alertname }}",
|
||||
"labels" : "{{ alert_payload.labels | tojson() }}"
|
||||
}
|
||||
#### `event`
|
||||
|
||||
> **NOTE:** If you receive an error message and cannot create an outgoing webhook, verify that your JSON is
|
||||
> formatted correctly.
|
||||
Context information about the event that triggered the outgoing webhook.
|
||||
|
||||
- `{{ event.type }}` - Lower case string matching [type of event](#event-types)
|
||||
- `{{ event.time }}` - Time event was triggered
|
||||
|
||||
#### `user`
|
||||
|
||||
Information about the user if the source of the event was a user. If a user acknowledges an alert group after
|
||||
receiving a notification this field will have that user's information. If an alert group was auto-resolved based
|
||||
on criteria in the integration this field will be empty.
|
||||
|
||||
- `{{ user.id }}` - [UID](#uid) of the user within Grafana OnCall
|
||||
- `{{ user.username }}` - Username in Grafana
|
||||
- `{{ user.email }}` - Email associated with user's Grafana account
|
||||
|
||||
#### `alert_group`
|
||||
|
||||
Details about the alert group associated with this event.
|
||||
|
||||
- `{{ alert_group.id }}` - [UID](#uid) of alert group
|
||||
- `{{ alert_group.integration_id }}` - [UID](#uid) of integration that alert came through
|
||||
- `{{ alert_group.route_id }}` - [UID](#uid) of route of integration that alert came through
|
||||
- `{{ alert_group.alerts_count }}` - Count of alerts in alert group
|
||||
- `{{ alert_group.state }}` - Current state of alert group
|
||||
- `{{ alert_group.created_at }}` - Timestamp alert group was created
|
||||
- `{{ alert_group.resolved_at }}` - Timestamp alert group was resolved (None if not resolved yet)
|
||||
- `{{ alert_group.acknowledged_at }}` - Timestamp alert group was acknowledged (None if not acknowledged yet)
|
||||
- `{{ alert_group.title }}` - Title of alert group
|
||||
- `{{ alert_group.permalinks }}` - Links to alert group in web and chat ops if available
|
||||
|
||||
#### `{{ alert_group_id }}`
|
||||
|
||||
UID of alert group, same as `{{ alert_group.id }}` (For convenience and compatibility with earler versions of Grafana OnCall)
|
||||
|
||||
#### `alert_payload`
|
||||
|
||||
Content of the first alert in the alert group. Content will depend on what the alert source has sent.
|
||||
Some commonly used fields are:
|
||||
|
||||
- `{{ alert_payload.labels.alertname }}`
|
||||
- `{{ alert_payload.annotations.description }}`
|
||||
|
||||
#### `integration`
|
||||
|
||||
Details about the integration that received this alert
|
||||
|
||||
- `{{ integration.id }}` - [UID](#uid) of integration
|
||||
- `{{ integration.type }}` - Type of integration (grafana, alertmanager, webhook, etc.)
|
||||
- `{{ integration.name }}` - Name of integration
|
||||
- `{{ integration.team }}` - Team integration belongs to if integration is assigned to a team
|
||||
|
||||
#### `notified_users`
|
||||
|
||||
Array of users that have received notifications about the associated alert group. Each user element in the array
|
||||
consists of `id`,`username`,`email`. Depending on timing of events and notifications this might not be populated yet
|
||||
if notifications are still in progress. Access as `{{ notified_users[0].username }}` for example.
|
||||
|
||||
#### `users_to_notify`
|
||||
|
||||
Array of users that could potentially be notified based on the configured escalation chain. Each user element in the array
|
||||
consists of `id`,`username`,`email`. Array elements are ordered based on the order users will be notified with the
|
||||
first element being the user that will be notified next. Like `notified_users` depending on timing of notifications
|
||||
a user in this array may have already been notified by the time this data is being processed. Access as
|
||||
`{{ users_to_notify[0].username }}` for example.
|
||||
|
||||
#### `responses`
|
||||
|
||||
The responses field is used to access the response data of other webhooks that are associated with this alert group.
|
||||
The keys inside responses are the [UID](#uid) of other outgoing webhooks. The values inside each response is the latest
|
||||
response of the referenced webhook when it was executed on behalf of the current alert group.
|
||||
See [Advanced Usage - Using response data](#using-response-data) for more details. Access as
|
||||
`{{ responses["WHP936BM1GPVHQ"].content.message }}` for example
|
||||
|
||||
### UID
|
||||
|
||||
Templates often use UIDs to make decisions about what actions to take if you need to find the UID of an object
|
||||
in the user interface to reference they can be found in the following places:
|
||||
|
||||
- Outgoing Webhook - In the table there is an info icon, UID displayed on hover, click to copy to clipboard
|
||||
- Integration - In integrations beside the name is an info icon, UID displayed on hover, click to copy to clipboard
|
||||
- Routes - With an integration selected beside Send Demo Alert is an infor icon, UID displayed on hover,
|
||||
click to copy to clipboard
|
||||
- Alert group - When viewing an alert group UID is visible in the browser URL
|
||||
- User - When viewing a user's profile UID is visible in the browser URL
|
||||
|
||||
UIDs are also visible in the browser URL when a specific object is selected for view or edit.
|
||||
|
||||
### Template examples
|
||||
|
||||
The following is an example of an entry in the Data field that would return an alert name and description.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "{{ alert_payload.labels.alertname }}",
|
||||
"message": "{{ alert_payload.annotations.description }}"
|
||||
}
|
||||
```
|
||||
|
||||
Here is an example using the user's email address as part of a URL:
|
||||
|
||||
```bash
|
||||
https://someticketsystem.com/new-ticket?assign-user={{ user.email }}
|
||||
```
|
||||
|
||||
#### Note about JSON
|
||||
|
||||
Take this template for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"labels" : "{{ alert_payload.labels }}"
|
||||
}
|
||||
```
|
||||
|
||||
It will result in the following (Invalid JSON due to single quotes):
|
||||
|
||||
```json
|
||||
{
|
||||
"labels": {'region': 'eu-1', 'alertname': 'TestAlert'}
|
||||
}
|
||||
```
|
||||
|
||||
To fix change the template to:
|
||||
|
||||
```json
|
||||
{
|
||||
"labels" : "{{ alert_payload.labels | tojson()}}"
|
||||
}
|
||||
```
|
||||
|
||||
Now the result is correct:
|
||||
|
||||
```json
|
||||
{
|
||||
"labels": {
|
||||
"alertname": "TestAlert",
|
||||
"region": "eu-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Event types
|
||||
|
||||
### Escalation Step
|
||||
|
||||
`event.type` `escalation`
|
||||
|
||||
This event will trigger when the outgoing webhook is included as a step in an escalation chain.
|
||||
|
||||
### Alert Group Created
|
||||
|
||||
`event.type` `alert group created`
|
||||
|
||||
This event will trigger when a new alert group is created.
|
||||
|
||||
### Acknowledged
|
||||
|
||||
`event.type` `acknowledge`
|
||||
|
||||
This event will trigger when a user acknowledges an alert group or an alert group is auto-acknowledged
|
||||
by the integration.
|
||||
|
||||
### Resolved
|
||||
|
||||
`event.type` `resolve`
|
||||
|
||||
This event will trigger when a user resolves an alert group or an alert group is auto-resolved
|
||||
by the integration.
|
||||
|
||||
### Silenced
|
||||
|
||||
`event.type` `silence`
|
||||
|
||||
This event will trigger when a user silences an alert group.
|
||||
|
||||
### Unsilenced
|
||||
|
||||
`event.type` `unsilence`
|
||||
|
||||
This event will trigger when a user unsilences an alert group or a silence expires.
|
||||
|
||||
### Unresolved
|
||||
|
||||
`event.type` `unresolve`
|
||||
|
||||
This event will trigger when a user unresolves an alert group.
|
||||
|
||||
### Unacknowledged
|
||||
|
||||
`event.type` `unacknowledge`
|
||||
|
||||
This event will trigger when a user unacknowledges an alert group.
|
||||
|
||||
## Viewing status of outgoing webhooks
|
||||
|
||||
In the outgoing webhooks table if a webhook is enabled **Last Run** will have the following information:
|
||||
|
||||
- Timestamp outgoing webhook was triggered
|
||||
- HTTP response code
|
||||
|
||||
If more information is required you can click **Status** in the table. The status drawer shows the following:
|
||||
|
||||
- Webhook Name
|
||||
- Webhook UID
|
||||
- Trigger Type
|
||||
- Last Run Time
|
||||
- URL
|
||||
- Response Code
|
||||
- Response Body
|
||||
- Trigger Template
|
||||
- Request Headers
|
||||
- Request Data
|
||||
|
||||
In the status drawer if a field makes use of a template it will display both the template and the result
|
||||
otherwise it will only display the value. Fields which are not used are not shown.
|
||||
|
||||
## Advanced usage
|
||||
|
||||
### Using trigger template field
|
||||
|
||||
The [trigger template field](#trigger-type) can be used to provide control over whether a webhook will execute.
|
||||
This is useful in situations where many different kinds of alerts are going to the same integration but only some of
|
||||
them should call the webhook. To accomplish this the trigger template field can contain a template that will process
|
||||
data from the alert group and evaluate to empty, True or 1 if the webhook should execute, any other values will result
|
||||
in the webhook not executing.
|
||||
|
||||
### Using response data
|
||||
|
||||
The `responses` section of the payload makes available the responses of other webhooks that have acted on the same
|
||||
alert group. To access them `responses` uses the `id` of the webhook as a key. The `id` can be found by hovering
|
||||
over the info icon, clicking will copy the `id` to the clipboard. The response data of the most recent
|
||||
execution of the webhook for this same alert group can be accessed this way.
|
||||
|
||||
The typical application of this is where a webhook will create a ticket in another system and OnCall needs to use
|
||||
the `id` of that ticket to keep its status synchronized with the state changes being made in OnCall.
|
||||
|
||||
### Advanced examples
|
||||
|
||||
Integrate with third-party services:
|
||||
|
||||
- [JIRA]({{< relref "../integrations/jira" >}})
|
||||
- [ServiceNow]({{< relref "../integrations/servicenow" >}})
|
||||
- [Zendesk]({{< relref "../integrations/zendesk" >}})
|
||||
|
||||
{{< section >}}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue