centralcloud/oncall-engine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oncall-engine/docs/sources/oncall-api-reference/outgoing_webhooks.md
Matias Bordese 576fecf6d3
feat: add personal webhook notification backend (#5426) 
Related to https://github.com/grafana/irm/issues/332

(see https://github.com/grafana/oncall/pull/5440 and
https://github.com/grafana/oncall/pull/5446 for the related UI changes)

---------

Co-authored-by: Matt Thorning <matt.thorning@grafana.com>
2025-02-18 17:53:07 +00:00

266 lines
11 KiB
Markdown
Raw Permalink Blame History

---
canonical: https://grafana.com/docs/oncall/latest/oncall-api-reference/outgoing_webhooks/
title: Outgoing webhooks HTTP API
weight: 0
refs:
outgoing-webhooks:
- pattern: /docs/oncall/
destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/outgoing-webhooks/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/outgoing-webhooks/
event-types:
- pattern: /docs/oncall/
destination: /docs/oncall/<ONCALL_VERSION>/configure/integrations/outgoing-webhooks/#event-types
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/oncall/configure/integrations/outgoing-webhooks/#event-types
pagination:
- pattern: /docs/oncall/
destination: /docs/oncall/<ONCALL_VERSION>/oncall-api-reference/#pagination
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/alerting-and-irm/oncall/oncall-api-reference/#pagination
---
# Outgoing webhooks
> ⚠️ A note about actions: Before version **v1.3.11** webhooks existed as actions within the API, the /actions
> endpoint remains available and is compatible with previous callers but under the hood it will interact with the
> new webhooks objects. It is recommended to use the /webhooks endpoint going forward which has more features.
For more details about specific fields of a webhook, refer to [Outgoing webhooks](ref:outgoing-webhooks).
## List webhooks
**Required permission**: `grafana-oncall-app.outgoing-webhooks:read`
```shell
curl "{{API_URL}}/api/v1/webhooks/" \
--request GET \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json"
```
The above command returns JSON structured in the following way:
```json
{
"next": null,
"previous": null,
"results": [
{
"id": "{{WEBHOOK_UID}}",
"name": "Demo Webhook",
"is_webhook_enabled": true,
"team": null,
"data": "{\"labels\" : {{ alert_payload.commonLabels | tojson()}}}",
"username": null,
"password": null,
"authorization_header": "****************",
"trigger_template": null,
"headers": null,
"url": "https://example.com",
"forward_all": false,
"http_method": "POST",
"trigger_type": "acknowledge",
"integration_filter": [
"CRV8A5MXC751A"
]
}
],
"page_size": 50,
"count": 1,
"current_page_number": 1,
"total_pages": 1
}
```
> **Note**: The response is [paginated](ref:pagination). You may need to make multiple requests to get all records.
## Get webhook
**Required permission**: `grafana-oncall-app.outgoing-webhooks:read`
```shell
curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
--request GET \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json"
```
The above command returns JSON structured in the following way:
```json
{
"id": "{{WEBHOOK_UID}}",
"name": "Demo Webhook",
"is_webhook_enabled": true,
"team": null,
"data": "{\"labels\" : {{ alert_payload.commonLabels | tojson()}}}",
"username": null,
"password": null,
"authorization_header": "****************",
"trigger_template": null,
"headers": null,
"url": "https://example.com",
"forward_all": false,
"http_method": "POST",
"trigger_type": "acknowledge",
"integration_filter": [
"CRV8A5MXC751A"
]
}
```
## Create webhook
**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
```shell
curl "{{API_URL}}/api/v1/webhooks/" \
--request POST \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json" \
--data '{
"name": "New Webhook",
"url": "https://example.com",
"http_method": "POST",
"trigger_type" : "resolve"
}'
```
### Trigger Types
For more detail, refer to [Event types](ref:event-types).
- `escalation`
- `personal notification`
- `alert group created`
- `acknowledge`
- `resolve`
- `silence`
- `unsilence`
- `unresolve`
- `unacknowledge`
- `status change`
### HTTP Methods
- `POST`
- `GET`
- `PUT`
- `DELETE`
- `OPTIONS`
The above command returns JSON structured in the following way:
```json
{
"id": "{{WEBHOOK_UID}}",
"name": "New Webhook",
"is_webhook_enabled": true,
"team": null,
"data": null,
"username": null,
"password": null,
"authorization_header": null,
"trigger_template": null,
"headers": null,
"url": "https://example.com",
"forward_all": true,
"http_method": "POST",
"trigger_type": "resolve",
"integration_filter": null
}
```
## Update webhook
**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
```shell
curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
--request PUT \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json" \
--data '{
"is_webhook_enabled": false
}'
```
The above command returns JSON structured in the following way:
```json
{
"id": "{{WEBHOOK_UID}}",
"name": "New Webhook",
"is_webhook_enabled": false,
"team": null,
"data": null,
"username": null,
"password": null,
"authorization_header": null,
"trigger_template": null,
"headers": null,
"url": "https://example.com",
"forward_all": true,
"http_method": "POST",
"trigger_type": "resolve",
"integration_filter": null
}
```
## Delete webhook
**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
```shell
curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
--request DELETE \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json"
```
## Get webhook responses
```shell
curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/responses" \
--request GET \
--header "Authorization: meowmeowmeow" \
--header "Content-Type: application/json"
```
The above command returns JSON structured in the following way:
```json
{
"next": null,
"previous": null,
"results": [
{
"timestamp": "2023-08-18T16:38:23.106015Z",
"url": "https://example.com",
"request_trigger": "",
"request_headers": "{\"Authorization\": \"****************\"}",
"request_data": "{\"labels\": {\"alertname\": \"InstanceDown\", \"job\": \"node\", \"severity\": \"critical\"}}",
"status_code": 200,
"content": "",
"event_data": "{\"event\": {\"type\": \"acknowledge\", \"time\": \"2023-08-18T16:38:21.442981+00:00\"}, \"user\": {\"id\": \"UK49JJNPZMFLJ\", \"username\": \"oncall\", \"email\": \"admin@localhost\"}, \"alert_group\": {\"id\": \"IZQERPWKWCGH1\", \"integration_id\": \"CRV8A5MXC751A\", \"route_id\": \"RWNCT6C77M3WM\", \"alerts_count\": 1, \"state\": \"acknowledged\", \"created_at\": \"2023-08-18T16:34:27.678406Z\", \"resolved_at\": null, \"acknowledged_at\": \"2023-08-18T16:38:21.442981Z\", \"title\": \"[firing:2] InstanceDown \", \"permalinks\": {\"slack\": null, \"telegram\": null, \"web\": \"http://localhost:3000/a/grafana-oncall-app/alert-groups/IZQERPWKWCGH1\"}}, \"alert_group_id\": \"IZQERPWKWCGH1\", \"alert_payload\": {\"alerts\": [{\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"production\", \"instance\": \"localhost:8081\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8081 down\", \"description\": \"localhost:8081 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f404ecabc8dd5cd7\", \"generatorURL\": \"\"}, {\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"canary\", \"instance\": \"localhost:8082\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8082 down\", \"description\": \"localhost:8082 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f8f08d4e32c61a9d\", \"generatorURL\": \"\"}], \"status\": \"firing\", \"version\": \"4\", \"groupKey\": \"{}:{alertname=\\\"InstanceDown\\\"}\", \"receiver\": \"combo\", \"numFiring\": 2, \"externalURL\": \"\", \"groupLabels\": {\"alertname\": \"InstanceDown\"}, \"numResolved\": 0, \"commonLabels\": {\"job\": \"node\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"truncatedAlerts\": 0, \"commonAnnotations\": {}}, \"integration\": {\"id\": \"CRV8A5MXC751A\", \"type\": \"alertmanager\", \"name\": \"One - Alertmanager\", \"team\": null}, \"notified_users\": [], \"users_to_be_notified\": []}"
},
{
"timestamp": "2023-08-18T16:34:38.580574Z",
"url": "https://example.com",
"request_trigger": "",
"request_headers": null,
"request_data": "Data - Template Warning: Object of type Undefined is not JSON serializable",
"status_code": null,
"content": null,
"event_data": "{\"event\": {\"type\": \"acknowledge\", \"time\": \"2023-08-18T16:34:37.940655+00:00\"}, \"user\": {\"id\": \"UK49JJNPZMFLJ\", \"username\": \"oncall\", \"email\": \"admin@localhost\"}, \"alert_group\": {\"id\": \"IZQERPWKWCGH1\", \"integration_id\": \"CRV8A5MXC751A\", \"route_id\": \"RWNCT6C77M3WM\", \"alerts_count\": 1, \"state\": \"acknowledged\", \"created_at\": \"2023-08-18T16:34:27.678406Z\", \"resolved_at\": null, \"acknowledged_at\": \"2023-08-18T16:34:37.940655Z\", \"title\": \"[firing:2] InstanceDown \", \"permalinks\": {\"slack\": null, \"telegram\": null, \"web\": \"http://localhost:3000/a/grafana-oncall-app/alert-groups/IZQERPWKWCGH1\"}}, \"alert_group_id\": \"IZQERPWKWCGH1\", \"alert_payload\": {\"alerts\": [{\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"production\", \"instance\": \"localhost:8081\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8081 down\", \"description\": \"localhost:8081 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f404ecabc8dd5cd7\", \"generatorURL\": \"\"}, {\"endsAt\": \"0001-01-01T00:00:00Z\", \"labels\": {\"job\": \"node\", \"group\": \"canary\", \"instance\": \"localhost:8082\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"status\": \"firing\", \"startsAt\": \"2023-06-12T08:24:38.326Z\", \"annotations\": {\"title\": \"Instance localhost:8082 down\", \"description\": \"localhost:8082 of job node has been down for more than 1 minute.\"}, \"fingerprint\": \"f8f08d4e32c61a9d\", \"generatorURL\": \"\"}], \"status\": \"firing\", \"version\": \"4\", \"groupKey\": \"{}:{alertname=\\\"InstanceDown\\\"}\", \"receiver\": \"combo\", \"numFiring\": 2, \"externalURL\": \"\", \"groupLabels\": {\"alertname\": \"InstanceDown\"}, \"numResolved\": 0, \"commonLabels\": {\"job\": \"node\", \"severity\": \"critical\", \"alertname\": \"InstanceDown\"}, \"truncatedAlerts\": 0, \"commonAnnotations\": {}}, \"integration\": {\"id\": \"CRV8A5MXC751A\", \"type\": \"alertmanager\", \"name\": \"One - Alertmanager\", \"team\": null}, \"notified_users\": [], \"users_to_be_notified\": []}"
}
],
"page_size": 50,
"count": 2,
"current_page_number": 1,
"total_pages": 1
}
```
> **Note**: The response is [paginated](ref:pagination). You may need to make multiple requests to get all records.
Reference in a new issue View git blame Copy permalink