Skip to content

Integrations setup

Integrations can be configured only via the YAML file!

Also, don't forget to restart the Kuvasz container after modifying the YAML file for the changes to take effect!

Your integrations are the channels through which Kuvasz sends notifications about the status of your monitors. You can use Kuvasz without any integrations, but it won't make much sense in most of the cases, because you won't be notified about any issues with your monitors.

Where to put them exactly?

You're free to put your integrations under integrations: in your YAML configuration file, wherever you like. The only restriction is that under integrations you can only use the integration types that are supported by Kuvasz.

How can they be referenced?

You can reference your integrations in your monitors by their ID, which is always dynamically generated by concatenating the type and name of the integration, separated by a colon (:). For example, if you have a Slack integration with the name slack-example, its ID will be slack:slack-example.

Tip

Find out more about assigning integrations to your monitors in the Managing monitors section of the documentation.

Common settings

All the integrations share some common, generic settings , which means that it doesn't matter which integration you configure, you can use the same settings for all of them.

Name

2.0.0 string name

The name of the integration. It must be unique across the given type of integration, so you can have multiple Slack integrations, for example, but they must have different names, and vice versa: you can have multiple integrations of different types with the same name. Can't be a blank string!

integrations:
  pagerduty:
    - name: "PD global integration"
      integration-key: YourOwnIntegrationKey

Enabled

2.0.0 true boolean enabled

Whether the integration is enabled or not. If it's set to false, the integration won't be used, and no notifications will be sent through it, however you can still reference it in your monitors.

integrations:
  pagerduty:
    - name: pd_global
      enabled: true
      integration-key: YourOwnIntegrationKey

Global

2.0.0 false boolean global

Whether the integration is global or not. If it's set to true, the integration will be used for all monitors by default, even if they don't have a specific integration assigned to them. If it's set to false, the integration will only be used for monitors that explicitly reference it.

integrations:
  pagerduty:
    - name: pd_global
      global: true
      integration-key: YourOwnIntegrationKey

Excluded events

3.8.0 empty list excluded-events

Integrations are listening to every event by default, but you can configure them to exclude specific events if you don't want to receive notifications for them.

The valid options are the following:

  • HTTP_UP
  • HTTP_DOWN
  • PUSH_UP
  • PUSH_DOWN
  • SSL_VALID
  • SSL_INVALID
  • SSL_WILL_EXPIRE

In case you don't specify any event types, or you provide an empty list, the integration will receive all the events.

integrations:
  pagerduty:
    - name: pd_global
      global: true
      excluded-events:
        - PUSH_DOWN
        - PUSH_UP
        - SSL_WILL_EXPIRE
      integration-key: YourOwnIntegrationKey

Slack

Configuration alias: slack

The Slack integration allows you to send notifications to a Slack channel via a webhook URL.

Webhook URL

2.0.0 string webhook-url

The webhook URL of the Slack channel where the notifications will be sent. You can create a webhook URL in your Slack workspace by following the official documentation.

Slack integration example
integrations:
  slack:
    - name: slack-example
      webhook-url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX'
    - name: slack-global
      webhook-url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX'
      global: true
    # ... other Slack integrations

Discord

Configuration alias: discord

The Discord integration allows you to send notifications to a Discord channel via a webhook URL.

Webhook URL

2.3.0 string webhook-url

The webhook URL of the Discord channel where the notifications will be sent. You can create a webhook URL in your Discord server by following these steps:

  1. Go to your Discord server settings
  2. Navigate to Integrations → Webhooks
  3. Click New Webhook
  4. Configure the webhook name and select the target channel
  5. Copy the Webhook URL

For more information, see the official Discord documentation.

Discord integration example
integrations:
  discord:
    - name: discord-example
      webhook-url: 'https://discord.com/api/webhooks/123456789/abcdef1234567890abcdef1234567890'
    - name: discord-global
      webhook-url: 'https://discord.com/api/webhooks/987654321/fedcba0987654321fedcba0987654321'
      global: true
    # ... other Discord integrations

Email

Configuration alias: email

The email integration allows you to send notifications via email. You can have multiple email integrations, each with its own sender and recipient addresses.

Warning

To make the email integration work, it's not enough to just configure the integration itself, you also need to set up the SMTP configuration in your YAML file. You can have multiple email integrations, but they will all use the same SMTP configuration.

For more information, see the SMTP configuration section of the documentation.

From address

2.0.0 string from-address

The email address from which the notifications will be sent. This is the address that will appear in the "From" field of the email.

To address

2.0.0 string to-address

The email address to which the notifications will be sent.

Email integration example
integrations:
  email:
    - name: email_implicitly_enabled
      from-address: noreply@kuvasz-uptime.dev
      to-address: your@email.address
    - name: email_disabled
      from-address: noreply@other-sender.com
      to-address: other-recipient@blabla.com
      enabled: false
    # ... other email integrations

PagerDuty

Configuration alias: pagerduty

The PagerDuty integration allows you to trigger incidents in PagerDuty when a monitor goes down, and to automatically resolve them when the monitor comes back up.

Things to do in PagerDuty first

  1. From the Configuration menu, select Services.
  2. There are two ways to add an integration to a service:
  3. If you are adding your integration to an existing service: Click the name of the service you want to add the integration to. Then, select the Integrations tab and click the New Integration button.
  4. If you are creating a new service for your integration: Please read our documentation in section Configuring Services and Integrations and follow the steps outlined in the Create a New Service section, selecting "Kuvasz" as the Integration Type in step 4. Continue with the "In Kuvasz" section (below) once you have finished these steps.
  5. Enter an Integration Name in the format monitoring-tool-service-name (e.g. Kuvasz-Your-Service) and select "Kuvasz" from the Integration Type menu.
  6. Click the Add Integration button to save your new integration. You will be redirected to the Integrations tab for your service.
  7. An Integration Key will be generated on this screen. Keep this key saved in a safe place, as it will be used when you configure the integration with Kuvasz in the next section. Copy PD key

Integration Key

2.0.0 string integration-key

The integration key of the PagerDuty service where the incidents will be created. You can find this key in your PagerDuty service settings.

PagerDuty integration example
integrations:
  pagerduty:
    - name: pd_global
      integration-key: YourOwnIntegrationKey
      global: true
    - name: pd_disabled
      integration-key: YourOtherIntegrationKey
      enabled: false
    # ... other PagerDuty integrations

Telegram

Configuration alias: telegram

The Telegram integration allows you to send notifications to a Telegram chat via a bot.

Getting your bot token and chat ID

  1. Create a new bot by talking to the BotFather on Telegram.
  2. After creating the bot, you will receive a bot token, this will be your api-token.
  3. Invite your bot to the chat where you want to receive notifications, or create a new group and add the bot to it.

  4. To get your chat ID, send a message to your desired chat and then visit https://api.telegram.org/bot<YourApiToken>/getUpdates in your browser, where <YourApiToken> is the token you received from the BotFather. Look for something like this in the response, this will be your chat-id:

    {
   // ... other fields ...
   "sender_chat": {
   "id": -343243243111,
   "title": "kuvasz uptime events",
   "type": "channel"
   },
   // ... other fields ...
}

API token

2.0.0 string api-token

The API token of the Telegram bot that will send the notifications. You can get this token from the BotFather when you create your bot.

Chat ID

2.0.0 string chat-id

The chat ID of the Telegram chat where the notifications will be sent. You can get this ID by following the steps outlined in the Getting your bot token and chat ID section.

Telegram integration example
integrations:
  telegram:
    - name: telegram_global
      api-token: 'YourToken'
      chat-id: '-1232642423121'
      global: true
    - name: telegram_disabled
      api-token: 'YourOtherToken'
      chat-id: '-1232546142423121'
      enabled: false
    # ... other Telegram integrations

Webhooks

Configuration alias: webhook

The Webhook integration allows you to send notifications to any endpoint that can receive HTTP POST requests. You can use it to integrate with 3rd party services that are not natively supported by Kuvasz, or to implement custom notification logic within your own infrastructure.

Warning

Make sure that your target endpoint handles POST requests and is able to process the payload sent by Kuvasz. Otherwise, you might end up with failed notifications and missed alerts.

The generic webhook message (if you don't use a custom template) has the following structure:

{
  "monitorId": "234 (6)",
  "monitorUrn": "http:GitHub API (1)",
  "monitorName": "GitHub API (2)",
  "monitorDetailsUrl": "/http-monitors/1 (7)",
  "timestamp": "1777661064488 (3)", 
  "type": "HTTP_DOWN (4)",
  "eventDetails": "Your monitor \"GitHub API\" (https://api.github.com) is DOWN. Reason: Connect Error: Connection refused: api.github.com (5)"
}
  1. monitorUrn: A unique identifier of a monitor, formatted as 'type:name'.
  2. monitorName: The name of the monitor, which must be unique.
  3. timestamp: The timestamp of the event that triggered the webhook, in milliseconds since the Unix epoch.
  4. type: The type of the event that triggered the webhook, which can be one of the following values: HTTP_UP, HTTP_DOWN, PUSH_UP, PUSH_DOWN, SSL_VALID, SSL_INVALID, SSL_WILL_EXPIRE.
  5. eventDetails: A human-readable message with more details about the event.
  6. monitorId: A unique, numeric ID of a monitor.
  7. monitorDetailsUrl: The relative URL to the monitor details page in the Kuvasz web interface.
GenericWebhookMessage:
  required:
  - monitorId
  - monitorUrn
  - monitorName
  - monitorDetailsUrl
  - timestamp
  - type
  - eventDetails
  type: object
  properties:
    monitorId:
      type: integer
      format: int64
    monitorUrn:
      type: string
    monitorName:
      type: string
    monitorDetailsUrl:
      type: string
    timestamp:
      type: integer
      format: int64
    type:
      type: string
      enum:
        - HTTP_UP
        - HTTP_DOWN
        - PUSH_UP
        - PUSH_DOWN
        - SSL_VALID
        - SSL_INVALID
        - SSL_WILL_EXPIRE
    eventDetails:
      type: string

Header & payload templates

Kuvasz uses the Pebble templating engine, so you can use all the features provided by Pebble in your templates, including conditionals, loops, filters, and more. Pebble is very similar to Twig (PHP) and Jinja (Python) in order to make it easy to use and understand, even if you didn't work with a JVM templating engine before.

For further information on how to use Pebble templates, please refer to the official documentation.

Strict variables

Keep in mind that template variables are handled in a strict way, which means that if you try to use a variable that is not available in the context, or if you make a typo in the variable name, the template rendering will fail and the request won't be sent. So make sure to double-check your templates and test them before using them in production.

Available context variables

The context variables are available in an object named ctx, and the structure is the same as the generic webhook message described above, so for example you can use {{ctx.monitorName}} to include the name of the monitor in your payload, or {{ctx.type}} to include the type of the event that triggered the webhook.

Having conflicting characters in your hard-coded headers?

In case your template would contain some characters that interfere with Pebble's own syntax, you can use the {% verbatim %} tag to bypass parsing them, like this:

request-headers:
  This-Should-Work-Too: "{% verbatim %}{%{% endverbatim %}" # Rendered as "{%"

Webhook examples for 3rd party services

You can find some examples of how to use the Webhook integration to integrate with 3rd party services here.

URL

3.8.0 string url

The URL of the endpoint where the notifications will be sent. This can be any URL that can receive HTTP requests, for example, an API endpoint of a 3rd party service, or an endpoint of your own backend.

Request headers

3.8.0 map request-headers

Optional HTTP headers that will be included in the requests sent to the target URL. This can be useful, for example, to include an Authorization header if the target endpoint requires authentication. The only header that is always included in the requests is the Content-Type header, which is set to application/json by default, but you can override it with your own value if needed.

Starting from version 3.9.0, you can also use templates in the header values, which allows you to include dynamic information in the headers based on the context of the event that triggered the webhook. For example, you can include the monitor name or the event type in a custom header by using a template like this:

request-headers:
  X-Monitor-Name: "{{ctx.monitorName}}"
  X-Event-Type: "{{ctx.type}}"

Payload template

3.8.0 string payload-template

You can customize the payload of the requests sent to the target URL by providing a payload template. This template can include any of the available context variables, which will be replaced with their actual values when the request is sent. This allows you to create custom payloads that fit the requirements of your target endpoint.

Webhook integration example
webhook:
  - name: webhook_templated
    url: https://any-other-http.service/webhooks
    excluded-events:
      - PUSH_UP
      - HTTP_UP
      - SSL_WILL_EXPIRE
    request-headers:
      Accept: '*/*'
      Authorization: Bearer your-webhook-secret-token
      X-Custom-Header: custom-value
    payload-template: |
      {
        "monitorName": "{{ctx.monitorName}}",
        "type": "{{ctx.type}}"
      }
  # ... other Webhook integrations

Testing integrations

It's vital to ensure that your integrations are correctly set up to receive notifications. You can test your integrations (even the disabled ones) directly either:

  • From the web interface by navigating to the Integrations page and clicking the button next to the integration you want to test. In this case you'll see the result in a visual way, at the same place where you initiated the test.
  • Via the API by sending a POST request to /api/v2/integrations/{integrationId}/test, where {integrationId} is the ID of the integration you want to test (for example, slack:your-desired-name). In this case the payload of the response should be straightforward to understand whether the test was successful or not.

Testing PagerDuty integrations

Please note that when testing PagerDuty integrations, a real incident will be created in your account, which will be immediately resolved by Kuvasz.

Testing webhook integrations

When you test a Webhook integration, a separate test message will be generated and sent for every event type that the integration watches, so for example if you have an integration that watches both HTTP_UP and HTTP_DOWN events, you will receive two separate messages in your target endpoint when you test the integration: one for the UP event and one for the DOWN event. The "down" events will be always fired first to simulate a real downtime scenario, and the "up" events will be fired immediately after to simulate the recovery of the monitor.

Integrations list

Do you miss an integration?

If you miss an integration, please open an issue, or consider contributing it yourself! We are always open to new integrations and would love to see your contribution.