Skip to content

Commit 5b834db

Browse files
ysyneuysyneu
authored
Merge pull request #996 from flashcatcloud/feat/pulseway-test
docs: add Pulseway alert integration
2 parents 42cf795 + 2239201 commit 5b834db

4 files changed

Lines changed: 291 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1714,6 +1714,7 @@
17141714
"zh/on-call/integration/alert-integration/alert-sources/alertsite",
17151715
"zh/on-call/integration/alert-integration/alert-sources/fivetran",
17161716
"zh/on-call/integration/alert-integration/alert-sources/coralogix",
1717+
"zh/on-call/integration/alert-integration/alert-sources/pulseway",
17171718
"zh/on-call/integration/alert-integration/alert-sources/uptimeobserver",
17181719
"zh/on-call/integration/alert-integration/alert-sources/rbltracker",
17191720
"zh/on-call/integration/alert-integration/alert-sources/dash0",
@@ -3346,6 +3347,7 @@
33463347
"en/on-call/integration/alert-integration/alert-sources/alertsite",
33473348
"en/on-call/integration/alert-integration/alert-sources/fivetran",
33483349
"en/on-call/integration/alert-integration/alert-sources/coralogix",
3350+
"en/on-call/integration/alert-integration/alert-sources/pulseway",
33493351
"en/on-call/integration/alert-integration/alert-sources/uptimeobserver",
33503352
"en/on-call/integration/alert-integration/alert-sources/rbltracker",
33513353
"en/on-call/integration/alert-integration/alert-sources/dash0",

‎en/on-call/integration/alert-integration/alert-sources/pulseway.mdx‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: "Pulseway alert integration"
3+
description: "Sync Pulseway RMM device notifications to Flashduty On-call through Pulseway notification webhooks."
4+
keywords: ["alert integration", "Pulseway", "RMM", "remote monitoring", "notification webhook", "webhook"]
5+
---
6+
7+
Pulseway is a remote monitoring and management (RMM) platform for IT teams and MSPs. When a device runs low on disk space, a service stops, a machine goes offline and so on, Pulseway raises a notification. This integration uses Pulseway notification webhooks and turns each notification into one Flashduty alert.
8+
9+
<div className="hide">
10+
11+
## In Flashduty On-call
12+
---
13+
14+
You can obtain an integration push URL in either of the following ways.
15+
16+
### Use a dedicated integration
17+
18+
1. In the Flashduty console, select **Channel** and open a channel
19+
2. Select **Configuration** → **Integrations** → **Private integration**, then click **Add an integration**
20+
3. Select **Pulseway**, then click **Save**
21+
4. Open the generated integration card and copy the **Push URL**
22+
23+
### Use a shared integration
24+
25+
1. In the Flashduty console, select **Integration Center → Alert Events**
26+
2. Select **Pulseway** and enter an integration name
27+
3. Configure the default route and select a channel; after creation, add more rules under **Route** if needed
28+
4. Click **Save** and copy the generated **Push URL**
29+
30+
</div>
31+
32+
## Configure Pulseway
33+
---
34+
35+
Pulseway notification webhooks are created through the REST API. One webhook covers every device in the selected organizations, and nothing is installed on the devices.
36+
37+
<Steps>
38+
<Step title="Prepare an API token">
39+
40+
Create a REST API token in the Pulseway web console and note the token ID and token secret. The REST API uses HTTP Basic authentication with the token ID as the user name and the token secret as the password. The token is only used to create the webhook; Flashduty does not need it.
41+
42+
</Step>
43+
44+
<Step title="Create the notification webhook">
45+
46+
Call `POST /v3/notifications/webhooks` and set `Url` to the full push URL of the Flashduty integration:
47+
48+
```bash
49+
curl -X POST https://api.pulseway.com/v3/notifications/webhooks \
50+
-u "<TOKEN_ID>:<TOKEN_SECRET>" \
51+
-H "Content-Type: application/json" \
52+
-d '{
53+
"Name": "Flashduty",
54+
"Url": "https://api.flashcat.cloud/event/push/alert/pulseway?integration_key=<your_integration_key>",
55+
"Priorities": ["Critical", "Elevated"],
56+
"Language": "en"
57+
}'
58+
```
59+
60+
| Field | Description |
61+
| :--- | :--- |
62+
| `Name` | Webhook name, to recognize it in the list |
63+
| `Url` | The push URL of the Flashduty integration, including `integration_key` |
64+
| `Priorities` | Notification priorities to send: `Low`, `Normal`, `Elevated`, `Critical`. Priorities not listed are not sent |
65+
| `OrganizationIds` | Optional. Limits the notifications to these organizations; leave it out to send all organizations |
66+
| `Language` | Optional. Language of the notification title and message, `en` or `de`; default `en` |
67+
68+
For a self-hosted Pulseway Enterprise Server, replace `https://api.pulseway.com/v3/` with `https://<your-server-name>/api/v3/`.
69+
70+
The `Id` in the response is the webhook ID; use `GET`, `PATCH` or `DELETE /v3/notifications/webhooks/<Id>` to view, change or delete the webhook later. The `SecretKey` in the response is what Pulseway uses to compute the `x-hmac-signature` header. Flashduty identifies the integration by the `integration_key` in the push URL and does not check that header, so you do not need to keep the key. Protect the push URL like a secret.
71+
72+
</Step>
73+
74+
<Step title="Turn on the auto-resolve timeout">
75+
76+
A Pulseway notification is a one-shot event: when the problem clears, Pulseway sends no recovery notification. In the channel that receives these alerts, turn on the [auto-resolve timeout](/en/on-call/channel/create-edit), counted from **Incident trigger**. Closing the incident also closes its alerts.
77+
78+
</Step>
79+
80+
<Step title="Verify">
81+
82+
On a monitored test device, trigger a notification at one of the selected priorities, for example by stopping a monitored service. The matching alert appears in Flashduty.
83+
84+
</Step>
85+
</Steps>
86+
87+
## Alert Key
88+
---
89+
90+
Flashduty uses the notification `Id` as the Alert Key, so each notification opens its own alert. While a problem persists, Pulseway notifies again with a new `Id`, which opens a new alert; the channel can group these alerts into one incident by rule. A device coming back online is a separate notification in Pulseway and does not close the earlier alert.
91+
92+
## Alert severity
93+
---
94+
95+
| Pulseway `Priority` | Flashduty severity |
96+
| :--- | :--- |
97+
| `Critical` | Critical |
98+
| `Elevated` | Warning |
99+
| `Normal` | Info |
100+
| `Low` | Info |
101+
| Other or empty | Warning |
102+
103+
Priority matching is case-insensitive.
104+
105+
## Labels
106+
---
107+
108+
| Label | Source |
109+
| :--- | :--- |
110+
| `check` | Notification title `Title` |
111+
| `resource` / `device_id` | Device ID `DeviceIdentifier` |
112+
| `organization_id` | Organization ID `OrganizationId` |
113+
| `priority` | Notification priority `Priority` |
114+
| `notification_id` | Notification ID `Id`, the source of the Alert Key |
115+
| `notified_at` | Notification time `DateTime` |
116+
117+
The alert title is the notification `Title` and the description is the notification `Message`.
118+
119+
## FAQ
120+
---
121+
122+
<AccordionGroup>
123+
124+
<Accordion title="No alert appears in Flashduty after creating the webhook?">
125+
126+
Use `GET /v3/notifications/webhooks` to confirm that `Url` is the full push URL and that `Priorities` includes the priority of the notifications that actually fire. With only `Critical` selected, an environment without serious problems sends nothing.
127+
128+
</Accordion>
129+
130+
<Accordion title="Do I need to configure signature verification?">
131+
132+
No. Flashduty identifies the integration only by `integration_key` and does not check `x-hmac-signature`.
133+
134+
</Accordion>
135+
136+
<Accordion title="Why does the alert never close?">
137+
138+
Pulseway sends no recovery notification. Turn on the auto-resolve timeout of the channel, or close the alert in Flashduty by hand.
139+
140+
</Accordion>
141+
142+
</AccordionGroup>
143+
144+
For field details, see [Pulseway REST API: Notification Webhooks](https://api.pulseway.com/).

‎integration-docs/src/doc-map.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ export const docMap = {
9999
Powerjob: `${alertBase}/powerjob.mdx`,
100100
Dolphinscheduler: `${alertBase}/dolphinscheduler.mdx`,
101101
AlertSite: `${alertBase}/alertsite.mdx`,
102+
Pulseway: `${alertBase}/pulseway.mdx`,
102103
Fivetran: `${alertBase}/fivetran.mdx`,
103104
Cato: `${alertBase}/cato.mdx`,
104105
Aikido: `${alertBase}/aikido.mdx`,

‎zh/on-call/integration/alert-integration/alert-sources/pulseway.mdx‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: "Pulseway 告警集成"
3+
description: "通过 Pulseway 通知 Webhook 将 RMM 设备通知同步到 Flashduty On-call。"
4+
keywords: ["告警集成", "Pulseway", "RMM", "远程监控", "通知 Webhook", "Webhook"]
5+
---
6+
7+
Pulseway 是面向 IT 团队和 MSP 的远程监控与管理（RMM）平台。设备出现磁盘空间不足、服务停止、离线等情况时，Pulseway 会生成一条通知。本集成使用 Pulseway 的通知 Webhook，把每条通知转成一条 Flashduty 告警。
8+
9+
<div className="hide">
10+
11+
## 在 Flashduty On-call
12+
---
13+
14+
您可通过以下两种方式获取集成推送地址，任选其一即可。
15+
16+
### 使用专属集成
17+
18+
1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
19+
2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
20+
3. 选择 **Pulseway**，点击 **保存**
21+
4. 打开生成的集成卡片，复制 **推送地址**
22+
23+
### 使用共享集成
24+
25+
1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
26+
2. 选择 **Pulseway**，填写集成名称
27+
3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
28+
4. 点击 **保存**，复制生成的 **推送地址**
29+
30+
</div>
31+
32+
## 在 Pulseway 中配置
33+
---
34+
35+
Pulseway 的通知 Webhook 通过 REST API 创建，一个 Webhook 覆盖所选组织下的全部设备，无需在设备上安装任何组件。
36+
37+
<Steps>
38+
<Step title="准备 API 令牌">
39+
40+
在 Pulseway Web 控制台中创建一个 REST API 令牌，记下令牌 ID 和令牌密钥。REST API 使用 HTTP Basic 认证，用户名为令牌 ID，密码为令牌密钥。令牌只在创建 Webhook 时使用，Flashduty 不需要它。
41+
42+
</Step>
43+
44+
<Step title="创建通知 Webhook">
45+
46+
调用 `POST /v3/notifications/webhooks`，`Url` 填写 Flashduty 集成的完整推送地址：
47+
48+
```bash
49+
curl -X POST https://api.pulseway.com/v3/notifications/webhooks \
50+
-u "<TOKEN_ID>:<TOKEN_SECRET>" \
51+
-H "Content-Type: application/json" \
52+
-d '{
53+
"Name": "Flashduty",
54+
"Url": "https://api.flashcat.cloud/event/push/alert/pulseway?integration_key=<your_integration_key>",
55+
"Priorities": ["Critical", "Elevated"],
56+
"Language": "en"
57+
}'
58+
```
59+
60+
| 字段 | 说明 |
61+
| :--- | :--- |
62+
| `Name` | Webhook 名称，便于在列表中识别 |
63+
| `Url` | Flashduty 集成的推送地址，包含 `integration_key` |
64+
| `Priorities` | 要推送的通知优先级，可选 `Low`、`Normal`、`Elevated`、`Critical`。未列出的优先级不会推送 |
65+
| `OrganizationIds` | 可选。限定推送哪些组织的通知；不填则推送全部组织 |
66+
| `Language` | 可选。通知标题和内容的语言，`en` 或 `de`，默认 `en` |
67+
68+
自建 Pulseway Enterprise Server 时，把 `https://api.pulseway.com/v3/` 换成 `https://<your-server-name>/api/v3/`。
69+
70+
响应中的 `Id` 是 Webhook ID，之后可用 `GET`、`PATCH`、`DELETE /v3/notifications/webhooks/<Id>` 查看、修改或删除该 Webhook。响应中的 `SecretKey` 用于 Pulseway 计算 `x-hmac-signature` 请求头，Flashduty 通过推送地址中的 `integration_key` 识别集成，不校验该请求头，因此无需保存。请像保管密钥一样保管推送地址。
71+
72+
</Step>
73+
74+
<Step title="开启超时自动关闭">
75+
76+
Pulseway 通知是一次性事件：问题消除后 Pulseway 不会推送恢复通知。请在接收这些告警的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，计时起点选择 **故障触发**。故障关闭时，关联的告警一并关闭。
77+
78+
</Step>
79+
80+
<Step title="验证">
81+
82+
在一台受监控的测试设备上触发一条所选优先级的通知，例如停止一个已被监控的服务。Flashduty 中会出现对应的告警。
83+
84+
</Step>
85+
</Steps>
86+
87+
## Alert Key
88+
---
89+
90+
Flashduty 使用通知的 `Id` 作为 Alert Key，每条通知各自产生一条告警。同一问题持续存在时，Pulseway 会再次发出通知，新的通知有新的 `Id`，因此会产生新的告警；这些告警可以在协作空间中按规则聚合到同一个故障。设备恢复在线等情况在 Pulseway 中是另一条通知，不会关闭之前的告警。
91+
92+
## 告警等级
93+
---
94+
95+
| Pulseway `Priority` | Flashduty 告警等级 |
96+
| :--- | :--- |
97+
| `Critical` | Critical |
98+
| `Elevated` | Warning |
99+
| `Normal` | Info |
100+
| `Low` | Info |
101+
| 其他或为空 | Warning |
102+
103+
优先级不区分大小写。
104+
105+
## 标签
106+
---
107+
108+
| 标签 | 来源 |
109+
| :--- | :--- |
110+
| `check` | 通知标题 `Title` |
111+
| `resource` / `device_id` | 设备 ID `DeviceIdentifier` |
112+
| `organization_id` | 组织 ID `OrganizationId` |
113+
| `priority` | 通知优先级 `Priority` |
114+
| `notification_id` | 通知 ID `Id`，即 Alert Key 的来源 |
115+
| `notified_at` | 通知时间 `DateTime` |
116+
117+
告警标题为通知的 `Title`，描述为通知的 `Message`。
118+
119+
## 常见问题
120+
---
121+
122+
<AccordionGroup>
123+
124+
<Accordion title="创建 Webhook 后 Flashduty 没有告警？">
125+
126+
用 `GET /v3/notifications/webhooks` 确认 `Url` 是完整的推送地址，并且 `Priorities` 包含实际发生的通知优先级。只选 `Critical` 时，没有严重问题的环境不会产生任何推送。
127+
128+
</Accordion>
129+
130+
<Accordion title="需要配置签名校验吗？">
131+
132+
不需要。Flashduty 只通过 `integration_key` 识别集成，不校验 `x-hmac-signature`。
133+
134+
</Accordion>
135+
136+
<Accordion title="告警为什么一直不关闭？">
137+
138+
Pulseway 没有恢复通知。请开启协作空间的超时自动关闭，或在 Flashduty 中手动关闭告警。
139+
140+
</Accordion>
141+
142+
</AccordionGroup>
143+
144+
更多字段说明请参阅 [Pulseway REST API：Notification Webhooks](https://api.pulseway.com/)。

0 commit comments

Comments
 (0)