Skip to main content
Kuvasz is an open-source, self-hosted uptime and SSL certificate monitor. Its webhook integration posts one JSON body to the configured URL whenever a monitor changes state (the default body, no custom template needed). Each monitor maps to one Flashduty alert: it opens when the monitor goes down and closes automatically when it recovers.

In Flashduty On-call

You can get the integration push URL in either of the following ways.

Use a dedicated integration

  1. In the Flashduty console, select Channel and open a channel
  2. Select Configuration → Integrations → Private integration, then click Add integration
  3. Select Kuvasz and click Save
  4. Open the generated integration card and copy the Push URL

Use a shared integration

  1. In the Flashduty console, go to Integration Center → Alert Events
  2. Select Kuvasz and enter an integration name
  3. Configure the default route and select a channel. You can add more rules under Routing after creation
  4. Click Save and copy the generated Push URL

Configure Kuvasz

Kuvasz integrations are configured only in the YAML configuration file, and you must restart the Kuvasz container after changing it.
1

Add a webhook integration to the Kuvasz configuration file

Where: Kuvasz configuration file (YAML) › integrations › webhook
To limit the integration to some monitors, remove global and reference the integration ID webhook:flashduty in those monitors’ configuration. The integration ID is the type plus the name.If you set excluded-events, do not exclude the *_UP events or SSL_VALID, or alerts will never recover.
2

Restart Kuvasz and send a test event

Where: Kuvasz web UI › IntegrationsChanges to the configuration file take effect only after you restart the Kuvasz container. After the restart, click the test button next to the integration on the Integrations page (or call POST /api/v2/integrations/{integrationId}/test). Kuvasz sends one sample message per monitor event type, all for a monitor named Test monitor. Flashduty recognizes these samples, returns 200, and creates no alert, so the test only proves connectivity.
3

Verify the lifecycle

Make a monitor actually fail (for example, create an HTTP monitor that points to a URL returning 500) and confirm Flashduty receives a Critical alert and the integration shows Latest event time. Point it back to a healthy URL and, once Kuvasz detects the recovery, confirm the alert closes.

Alert key

Flashduty uses the monitor type plus monitorId as the Alert Key. Each Kuvasz monitor has a fixed numeric ID, and the down (*_DOWN) and up (*_UP) messages of one monitor carry the same monitorId, so they land on the same Flashduty alert.
  • Monitor IDs are independent per monitor type (HTTP monitor 12 and TCP monitor 12 are different monitors), so the Alert Key also contains the monitor type (HTTP, Push, ICMP, TCP, DNS, Docker)
  • SSL certificate events use a separate Alert Key, so an HTTP monitor’s recovery message does not close them
  • Renaming a monitor does not change the Alert Key
Flashduty rejects requests that have no monitorId.

Alert lifecycle

Flashduty handles messages by the type field: Other types are ignored as well. DNS_RECORDS_CHANGED has no recovery message, so turn on auto-close after timeout for the channel, start the timer from Incident triggered, and set about 24 hours.

Status and severity

Kuvasz messages carry no severity. Down events and SSL_INVALID mean the service is unavailable and are fixed at Critical; SSL_WILL_EXPIRE and DNS_RECORDS_CHANGED are fixed at Warning. A recovery event keeps the original alert’s severity.

Alert content

  • Title: the monitor name
  • Description: the event text Kuvasz generates (eventDetails)
  • Labels: check (monitor name), monitor_id, monitor_type, monitor_name, monitor_urn, monitor_detail (relative path of the monitor’s details page), event_type (Kuvasz type), and source (always kuvasz)

Troubleshooting

  • The test event created no alert: this is expected; test events only verify connectivity
  • 4xx or an invalid integration_key error: check that url is the full push URL and the integration is not disabled
  • An alert did not recover: check that excluded-events does not exclude *_UP or SSL_VALID, and that no custom payload-template is set (a custom template changes the fields, which Flashduty cannot recognize)
For the full option reference, see the Kuvasz Integrations documentation.