|
| 1 | +--- |
| 2 | +title: "Apache HertzBeat Alert Integration" |
| 3 | +description: "Send Apache HertzBeat alerts and recoveries to Flashduty On-call through a Webhook notice receiver." |
| 4 | +keywords: ["alert integration", "Apache HertzBeat", "HertzBeat", "webhook", "notice receiver", "monitoring", "alert rules"] |
| 5 | +--- |
| 6 | + |
| 7 | +Use the Webhook type of a notice receiver under **Alarm Notification → Notice Receiver** in Apache HertzBeat to sync alert rule triggers (`firing`) and recoveries (`resolved`) to Flashduty On-call. Each alert rule on each monitored target maps to one Flashduty alert: it is created when the rule fires and closed automatically when it resolves. |
| 8 | + |
| 9 | +<div className="hide"> |
| 10 | + |
| 11 | +## In Flashduty On-call |
| 12 | +--- |
| 13 | + |
| 14 | +Get the push URL in either of two ways. |
| 15 | + |
| 16 | +### Use a dedicated integration |
| 17 | + |
| 18 | +1. In the Flashduty console, select **Channels** and open a channel |
| 19 | +2. Select **Settings** → **Integration data** → **Dedicated integration**, then click **Add an integration** |
| 20 | +3. Select **Apache HertzBeat** and 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 **Apache HertzBeat** and enter an integration name |
| 27 | +3. Set the default route and pick a channel; you can add more rules under **Routes** after creation |
| 28 | +4. Click **Save** and copy the generated **push URL** |
| 29 | + |
| 30 | +</div> |
| 31 | + |
| 32 | +## Configure HertzBeat |
| 33 | +--- |
| 34 | + |
| 35 | +<Steps> |
| 36 | +<Step title="Add a notice receiver"> |
| 37 | + |
| 38 | +1. Log in to HertzBeat and go to **Alarm Notification → Notice Receiver → Add Receiver** |
| 39 | +2. Select **WebHook** as the notification method |
| 40 | +3. Paste the full Flashduty push URL into the callback address |
| 41 | +4. Save. You can click **Send test message** to check connectivity |
| 42 | + |
| 43 | +</Step> |
| 44 | + |
| 45 | +<Step title="Add a notice policy"> |
| 46 | + |
| 47 | +A new receiver gets no alerts by itself. Under **Alarm Notification → Notice Policy**, add a policy that selects the receiver and, if needed, the severities and labels to notify, then save. |
| 48 | + |
| 49 | +</Step> |
| 50 | + |
| 51 | +<Step title="Verify the lifecycle"> |
| 52 | + |
| 53 | +Make an alert rule fire (for example, stop a monitored port) and confirm Flashduty receives an active alert. When the rule condition no longer holds, HertzBeat sends a `resolved` notification and the Flashduty alert recovers automatically. |
| 54 | + |
| 55 | +</Step> |
| 56 | +</Steps> |
| 57 | + |
| 58 | +<Warning> |
| 59 | +Flashduty parses only the default Webhook template that ships with HertzBeat. If you edit the receiver's custom template, the body changes and Flashduty cannot guarantee it parses. Custom templates are not supported. |
| 60 | +</Warning> |
| 61 | + |
| 62 | +## Payload |
| 63 | +--- |
| 64 | + |
| 65 | +HertzBeat POSTs the default template as JSON. One request can carry several alerts in `alerts`, and Flashduty handles each one: |
| 66 | + |
| 67 | +| Field | Meaning | In Flashduty | |
| 68 | +| :--- | :--- | :--- | |
| 69 | +| `status` | `firing` or `resolved`, shared by the whole request | Trigger or recovery | |
| 70 | +| `alerts[].labels.alertname` | Alert rule name | Alert title, labels `check` and `alertname` | |
| 71 | +| `alerts[].labels.instance` | Monitored target | Labels `resource` and `instance` | |
| 72 | +| `alerts[].labels.defineid` | Alert rule ID | Label `defineid` | |
| 73 | +| `alerts[].labels.severity` | Severity defined in the rule | Alert severity, label `severity` | |
| 74 | +| `alerts[].content` | Alert content | Alert description | |
| 75 | +| `alerts[].annotations` | Annotations defined in the rule | Alert description, sorted by key, one `key: value` per line | |
| 76 | +| Other keys in `alerts[].labels` | For example `instancename` and custom rule labels | Labels of the same name | |
| 77 | + |
| 78 | +`commonLabels` and `commonAnnotations` are not read. |
| 79 | + |
| 80 | +## Alert Key |
| 81 | +--- |
| 82 | + |
| 83 | +The HertzBeat payload carries no alert ID. Flashduty builds the Alert Key from `alertname`, `instance` and `defineid` in `alerts[].labels`. In real HertzBeat 1.9.0 deliveries these three values were identical on trigger, repeated notification while firing, and recovery, so all three land on one Flashduty alert. Changing the severity, content or monitor name does not change the Alert Key. |
| 84 | + |
| 85 | +A request without `labels.alertname` is rejected with a parameter error, because a recovery could not be tied to its alert. A missing `instance` or `defineid` counts as empty. |
| 86 | + |
| 87 | +## Status and severity |
| 88 | +--- |
| 89 | + |
| 90 | +| HertzBeat field | Flashduty status or severity | |
| 91 | +| :--- | :--- | |
| 92 | +| `labels.severity` = `critical` | Critical | |
| 93 | +| `labels.severity` = `warning`, empty or any other value | Warning | |
| 94 | +| `labels.severity` = `info` | Info | |
| 95 | +| `status` = `firing` | Trigger or update the alert, severity from the table above | |
| 96 | +| `status` = `resolved` | Recovery; the alert keeps its severity | |
| 97 | + |
| 98 | +A request with any other `status`, or an empty `alerts`, is rejected. In the default template `commonLabels.severity` is rewritten to decorated text (such as "Critical"), so it is not used for severity. |
| 99 | + |
| 100 | +## FAQ |
| 101 | +--- |
| 102 | + |
| 103 | +<AccordionGroup> |
| 104 | +<Accordion title="What does Flashduty show after I click Send test message?"> |
| 105 | + |
| 106 | +The button sends a fixed firing request (rule name `CPU Usage Alert`, instance `127.0.0.1`, content starting with `test send msg!`). Flashduty returns HTTP 200 and opens a separate Info alert under its own Alert Key, so it never merges into a real alert. No recovery follows; close it by hand in the channel. |
| 107 | + |
| 108 | +</Accordion> |
| 109 | + |
| 110 | +<Accordion title="Does a long-firing alert create duplicates?"> |
| 111 | + |
| 112 | +No. HertzBeat resends `firing` while the alert stays active. The Alert Key is the same, so Flashduty merges them into one alert. |
| 113 | + |
| 114 | +</Accordion> |
| 115 | + |
| 116 | +<Accordion title="An availability alert did not close in Flashduty after the monitor came back?"> |
| 117 | + |
| 118 | +Flashduty recovers an alert only when HertzBeat sends `resolved`. In one test on HertzBeat 1.9.0, an availability alert was still firing several minutes after the monitor came back and sent no `resolved`, while a metric-threshold rule did. If you see this, check in the HertzBeat alert center whether the alert has recovered. |
| 119 | + |
| 120 | +</Accordion> |
| 121 | +</AccordionGroup> |
| 122 | + |
| 123 | +## Troubleshooting |
| 124 | +--- |
| 125 | + |
| 126 | +- **Flashduty receives no alerts**: confirm the URL is the full push URL (with `integration_key`), a notice policy exists, and the alert matches it |
| 127 | +- **Flashduty returns a parameter error**: confirm the body is the default HertzBeat template JSON, `status` is `firing` or `resolved`, and every alert has `labels.alertname` |
| 128 | +- **An alert does not recover**: confirm HertzBeat sent `resolved` and that its `alertname`, `instance` and `defineid` equal those of the trigger |
| 129 | + |
| 130 | +For HertzBeat notification setup, see the official [Webhook notification](https://hertzbeat.apache.org/docs/help/alert_webhook/) guide. |
0 commit comments