diff --git a/docs/sources/integrations/jira/index.md b/docs/sources/integrations/jira/index.md index a337492c..3c7b4c70 100644 --- a/docs/sources/integrations/jira/index.md +++ b/docs/sources/integrations/jira/index.md @@ -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://.atlassian.net/rest/api/2/issue +``` + +Replace `` 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": "" + }, + "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 `` 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://.atlassian.net/rest/api/2/issue/{{responses..key}}/transitions +``` + +Replace `` with your Jira instance, and `` 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": "" + }, + "fields": { + "resolution": { + "name": "Done" + } + }, + "update": { + "comment": [ + { + "add": { + "body": "Resolved by Grafana OnCall.", + "public": false + } + } + ] + } +} +``` + +Replace `` 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//user-and-team-management" [user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management" diff --git a/docs/sources/integrations/servicenow/index.md b/docs/sources/integrations/servicenow/index.md new file mode 100644 index 00000000..4f839efb --- /dev/null +++ b/docs/sources/integrations/servicenow/index.md @@ -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://.service-now.com/api/now/table/incident +``` + +Replace `` 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]{{alert_group.id}}[/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://.service-now.com/api/now/table/incident/{{responses..result.sys_id}} +``` + +Replace `` with your ServiceNow instance, and `` 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://.service-now.com/api/now/table/incident/{{responses..result.sys_id}} +``` + +Replace `` with your ServiceNow instance, and `` 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). diff --git a/docs/sources/integrations/zendesk/index.md b/docs/sources/integrations/zendesk/index.md index e8b4f78d..708b0aee 100644 --- a/docs/sources/integrations/zendesk/index.md +++ b/docs/sources/integrations/zendesk/index.md @@ -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://.zendesk.com/api/v2/tickets +``` + +Replace `` 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://.zendesk.com/api/v2/tickets/{{responses..ticket.id}} +``` + +Replace `` with your Zendesk instance, and `` 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//user-and-team-management" [user-and-team-management]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/user-and-team-management" diff --git a/docs/sources/outgoing-webhooks/_index.md b/docs/sources/outgoing-webhooks/_index.md index a871b624..c58f6244 100644 --- a/docs/sources/outgoing-webhooks/_index.md +++ b/docs/sources/outgoing-webhooks/_index.md @@ -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 >}}