Skip to content

Commit 49906cd

Browse files
armiillerarmiiller
committed
Add better docs for the custom webhook
1 parent c947b32 commit 49906cd

1 file changed

Lines changed: 99 additions & 48 deletions

File tree

‎docs/integration-guides/custom-webhook.md‎

Lines changed: 99 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ description: >-
44
This allows advanced rule-based processing with YAML configurations.
55
---
66

7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
711
# Custom Webhook
812

913
| Company | Estimated Time | Vendor Docs | Open Source |
@@ -65,11 +69,87 @@ Define rules in YAML for matching and actions ([see examples below](#examples)).
6569
### In Your Source Tool
6670
Configure your tool (e.g., UptimeRobot, AWS SNS, etc.) to send `POST` requests to PagerTree's endpoint URL. The payload will be processed using your YAML rules.
6771

72+
## YAML Syntax Reference
73+
74+
### Rule Structure
75+
76+
``` yaml
77+
preprocess:
78+
# preprocessors
79+
# - type: parse_sns
80+
rules:
81+
- match:
82+
# conditions (see your specific tool's payload)
83+
# log.data.state: "alarm"
84+
actions:
85+
- type: create|acknowledge|resolve
86+
thirdparty_id: "{{log.data.id}}"
87+
default:
88+
actions:
89+
- type: ignore
90+
```
91+
92+
### Preprocessors
93+
94+
| Preprocessor | Description |
95+
| ------------ | ----------- |
96+
| `parse_json` | Converts a raw string into JSON. |
97+
| `parse_sns` | Processes AWS SNS payloads and parses the Notification `Message`. |
98+
99+
### Match Data
100+
The shape of the data passed in for you to match on is as follows:
101+
102+
```json
103+
{
104+
"always": true,
105+
"log": {
106+
"data": {
107+
/* Your tool's payload (a combition of any query parameters and JSON payload) (hash) */
108+
"key1": "value1",
109+
"key2": {
110+
"key3": 123
111+
}
112+
// ...
113+
},
114+
"headers": {
115+
/* Headers of the HTTP Request sent by your tool (hash) */
116+
"Content-Type": "application/json"
117+
// ...
118+
},
119+
"body": "", // Raw body of the payload (string).
120+
"params": {}, // Raw query parameters (hash).
121+
"method": "", // The HTTP verb (string).
122+
"url": "", // The URL that was called (string).
123+
"remote_ip": , // The IP that made the call (string).
124+
}
125+
}
126+
```
127+
128+
### Action Fields
129+
130+
| Field | Required? | Type | Purpose |
131+
| ------------------- | --------- | ------------- | ----------------------------------------------- |
132+
| `type` | ✅ | string | `create`, `acknowledge`, `resolve` |
133+
| `thirdparty_id` | ✅ | string | Identifier used for alert correlation. (see [integrations@alert-aggregation](../integrations.md#alert-aggregation)) |
134+
| `title` | on create | string | Alert title. |
135+
| `description` | - | string | Alert description. |
136+
| `urgency` | - | enum | `critical`, `high`, `medium`, `low`, `silent` |
137+
| `tags` | - | list/string | Alert tags. List (array). String (comma delimited) |
138+
| `meta` | - | object | Additional metadata (hash) |
139+
| `additional_data` | - | list | Supplemental visual fields (object) `{format: "text\|link\|img\|email\|phone\|datetime", label: "string", value: "string"}` |
140+
| `dedup_keys` | - | list/string | Global deduplication keys. List (array). String (command delimiated) |
141+
| `incident`| - | boolean | Boolean value `true\|false` if this alert should be flagged as an incident |
142+
| `incident_severity` | if `incident` true | string | `SEV-1`, `SEV-2`, `SEV-3`, `SEV-4`, `SEV-5` |
143+
| `incident_message` | if `incident` true | string | A custom message to be displayed at the top of the alert page |
144+
68145
## Examples
69146

70-
### Example: New Relic Integration (YAML)
71-
```yaml
147+
### Example: New Relic
72148

149+
<Tabs>
150+
<TabItem value="new-relic-yaml" label="new-relic.yaml" default>
151+
152+
```yaml
73153
---
74154
rules:
75155
- match:
@@ -104,8 +184,9 @@ default:
104184
reason: "Unhandled New Relic alert"
105185
```
106186

107-
### Example: New Relic Integration (cURL)
108-
```bash
187+
</TabItem>
188+
<TabItem value="new-relic-curl" label="New Relic (cURL)">
189+
```bash
109190
curl -X POST https://api.pagertree.com/integration/int_ABC123 \
110191
-H "Content-Type: application/json" \
111192
-d '{
@@ -149,8 +230,13 @@ curl -X POST https://api.pagertree.com/integration/int_ABC123 \
149230
"version": 3
150231
}'
151232
```
233+
</TabItem>
234+
</Tabs>
152235

153-
### Example: AWS SNS Cloudwatch (YAML)
236+
### Example: AWS SNS + Cloudwatch
237+
238+
<Tabs>
239+
<TabItem value="aws-sns-cloudwatch-yml" label="aws-sns-cloudwatch.yml" default>
154240

155241
```yaml
156242
---
@@ -200,59 +286,24 @@ rules:
200286
default:
201287
actions:
202288
- type: ignore
203-
reason: "Unhandled AWS Health Event"
289+
reason: "Unhandled CloudWatch Event"
204290
```
205291

206-
##### Example: AWS SNS Cloudwatch (cURL)
292+
</TabItem>
293+
<TabItem value="aws-sns-cloudwatch-curl" label="AWS SNS + Cloudwatch (cURL)">
207294

208295
```bash
209-
curl -X POST http://example.com \
296+
curl -X POST https://api.pagertree.com/integration/int_ABC123 \
210297
-H "Content-Type: text/plain" \
211298
--data-raw '{"Type": "Notification", "MessageId": "[REDACTED]", "TopicArn": "arn:aws:sns:us-west-2:[ACCOUNT_ID]:[TOPIC_NAME]", "Subject": "ALARM: \"[ALARM_NAME]\" in US West (Oregon)", "Message": "{\"AlarmName\": \"[ALARM_NAME]\", \"AlarmDescription\": null, \"AWSAccountId\": \"[ACCOUNT_ID]\", \"AlarmConfigurationUpdatedTimestamp\": \"2025-12-05T21:52:26.532+0000\", \"NewStateValue\": \"ALARM\", \"NewStateReason\": \"Threshold Crossed: 1 out of the last 1 datapoints [[DATAPOINT_VALUE] (05/12/25 21:50:00)] was not less than the threshold (1.0) (minimum 1 datapoint for OK -> ALARM transition).\", \"StateChangeTime\": \"2025-12-05T21:53:58.466+0000\", \"Region\": \"US West (Oregon)\", \"AlarmArn\": \"arn:aws:cloudwatch:us-west-2:[ACCOUNT_ID]:alarm:[ALARM_NAME]\", \"OldStateValue\": \"OK\", \"OKActions\": [\"arn:aws:sns:us-west-2:[ACCOUNT_ID]:[TOPIC_NAME]\"], \"AlarmActions\": [\"arn:aws:sns:us-west-2:[ACCOUNT_ID]:[TOPIC_NAME]\"], \"InsufficientDataActions\": [], \"Trigger\": {\"MetricName\": \"CallCount\", \"Namespace\": \"AWS/Usage\", \"StatisticType\": \"Statistic\", \"Statistic\": \"AVERAGE\", \"Unit\": null, \"Dimensions\": [{\"value\": \"API\", \"name\": \"Type\"}, {\"value\": \"SendLast24Hours\", \"name\": \"Resource\"}, {\"value\": \"SES\", \"name\": \"Service\"}, {\"value\": \"None\", \"name\": \"Class\"}], \"Period\": 60, \"EvaluationPeriods\": 1, \"DatapointsToAlarm\": 1, \"ComparisonOperator\": \"LessThanThreshold\", \"Threshold\": 1.0, \"TreatMissingData\": \"notBreaching\", \"EvaluateLowSampleCountPercentile\": \"\"}}", "Timestamp": "2025-12-05T21:53:58.509Z", "SignatureVersion": "1", "Signature": "[REDACTED]", "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-[REDACTED].pem", "UnsubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-west-2:[ACCOUNT_ID]:[TOPIC_NAME]:[SUBSCRIPTION_ID]"}'
212299
```
300+
</TabItem>
301+
</Tabs>
213302

214-
You have successfully completed the Custom Webhook Integration.
215-
216-
## YAML Syntax Reference
217303

218-
### Rule Structure
219-
220-
``` yaml
221-
preprocess:
222-
# preprocessors
223-
# - type: parse_sns
224-
rules:
225-
- match:
226-
# conditions (see your specific tool's payload)
227-
# log.data.state: "alarm"
228-
actions:
229-
- type: create|acknowledge|resolve
230-
thirdparty_id: "{{log.data.id}}"
231-
default:
232-
actions:
233-
- type: ignore
234-
```
304+
##### Example: AWS SNS Cloudwatch (cURL)
235305

236-
### Preprocessors
237306

238-
| Preprocessor | Description |
239-
| ------------ | ----------- |
240-
| `parse_json` | Converts a raw string into JSON. |
241-
| `parse_sns` | Processes AWS SNS payloads and parses the Notification `Message`. |
242307

243-
### Action Fields
308+
You have successfully completed the Custom Webhook Integration.
244309

245-
| Field |Type | Purpose |
246-
| ------------------- | ------------- | ----------------------------------------------- |
247-
| `type` | string | `create`, `acknowledge`, `resolve` |
248-
| `thirdparty_id` | string | Identifier used for alert correlation. (see [integrations@alert-aggregation](../integrations.md#alert-aggregation)) |
249-
| `title` | string | Alert title. |
250-
| `description` | string | Alert description. |
251-
| `urgency` | enum | `critical`, `high`, `medium`, `low`, `silent` |
252-
| `tags` | list/string | Alert tags. List (array). String (comma delimited) |
253-
| `meta` | object | Additional metadata (hash) |
254-
| `additional_data` | list | Supplemental visual fields (object) `{format: "text\|link\|img\|email\|phone\|datetime", label: "string", value: "string"}` |
255-
| `dedup_keys` | list/string | Global deduplication keys. List (array). String (command delimiated) |
256-
| `incident`| boolean | Boolean value `true\|false` if this alert should be flagged as an incident |
257-
| `incident_severity` | string | `SEV-1`, `SEV-2`, `SEV-3`, `SEV-4`, `SEV-5` |
258-
| `incident_message` | string | A custom message to be displayed at the top of the alert page |

0 commit comments

Comments
 (0)