How to manage Alert Receivers via API

Possible receivers

You can configure the following possible receivers:

• email
• webhook (Google Chat, Microsoft Teams or other)
• Opsgenie

To execute the following commands, you need to set your PROJECT_ID and INSTANCE_ID as environment variables (or replace them directly in the commands).

If you need help locating these identifiers or want to learn how the stackit curl wrapper works, refer to our central guide: Interacting with the Observability API.

How to add an email receiver

To create an email receiver, execute a POST request to the receiver endpoint. With the following HTTP message body, you have the minimum configuration to add a new email receiver:

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/receivers" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"MyEmailReceiver","emailConfigs":[{"to":"emailTo@your-company.com"}]}'

Per default, Observability will send all messages from a STACKIT Observability email address. Optionally, you can configure your own email address as the sender address. In this case, you need to provide SMTP credentials in your request body:

{
  "name": "MyEmailReceiver",
  "emailConfigs": [
    {
      "to": "emailTo@your-company.com",
      "from": "observability-alerting@your-company.com",
      "smarthost": "your-company.com",
      "authUsername": "username",
      "authPassword": "password",
      "authIdentity": "yourIdentity"
    }
  ]
}

More information about the API and the request body can be found in the API documentation.

Create a route using the receiver

You will also need to create an alert config route for the receiver you just created. Ensure the "receiver" name matches the one you defined above.

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/routes" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"receiver":"MyEmailReceiver","groupBy":["LatencyHigh"],"groupWait":"30s","groupInterval":"5m","repeatInterval":"4h"}'

More information on the expected request body can be found in the API documentation.

How to add a Webhook receiver

You can use any compatible webhook. To create a webhook receiver, execute a POST request to the receiver endpoint. Below is an example of a complete command for a custom webhook:

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/receivers" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"MyWebhookReceiver","webHookConfigs":[{"url":"https://your-webhook-url.com"}]}'

Webhook request body examples

If you are using Google Chat or Microsoft Teams, replace the JSON data in the --data parameter with one of the following structures (notice the specific parameters for each platform). More information can be found in the API documentation.

Google Chat Webhook

{
  "name": "MyGoogleChatWebhookReceiver",
  "webHookConfigs": [
    {
      "googleChat": true,
      "url": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
    }
  ]
}

MS Teams Webhook

{
  "name": "MyMsTeamsWebhookReceiver",
  "webHookConfigs": [
    {
      "msTeams": true,
      "url": "https://your-teams-webhook-url.com"
    }
  ]
}

Create a route using the receiver

Just like with the email receiver, you need to create an alert config route for the webhook receiver you just created. Please make sure to use the exact same name of the receiver.

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/routes" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"receiver":"MyReceiverName","groupBy":["LatencyHigh"],"groupWait":"30s","groupInterval":"5m","repeatInterval":"4h"}'

How to add an Opsgenie receiver

You can also configure your own Opsgenie. With the following HTTP message body, you have the minimum configuration to add a new Opsgenie receiver:

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/receivers" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"name":"MyOpsGenieReceiver","opsgenieConfigs":[{"apiKey":"yourApiKey","apiUrl":"yourApiURL","tags":"TagsYouWantToHave","httpConfig":{"proxyUrl":"yourProxyServerURL"}}]}'

More information about the API and the request body can be found in the API documentation.

Create a route using the receiver

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/routes" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"receiver":"MyOpsGenieReceiver","groupBy":["LatencyHigh"],"groupWait":"30s","groupInterval":"5m","repeatInterval":"4h"}'

How to check the configuration

Basic syntax checking is provided by the Observability API.

Grafana visualizes triggered Alerts:

• Log in to Grafana.
• Select the function Explore.
• Select the data source Thanos.
• Choose the metric ALERTS.
• Visualize the metric by clicking Run query.

If you don’t get any emails, please check your SPAM folder. Sometimes mail agents filter alert emails because they contain hyperlinks. Additionally, you should check if you’re using a global configuration for all email receivers. If yes, verify the global section of the response from the GET Alertconfigs endpoint. It should look like the response example in the next chapter.

How to reset the global configuration

By default, Observability sends all emails from a STACKIT Observability address. You can optionally configure your own email as a sender address. In this case, you need to provide SMTP credentials. You can either configure your individual email sender address globally or on a per-email receiver basis. To set it globally, use the global section of the body sent to the PUT Alertconfigs endpoint.

If you want to switch back to using our default email address for sending alerts, you can use the following JSON body with a minimal configuration for the PUT endpoint.

Be careful: If you leave the global section empty as shown in this example, everything inside will be overwritten with our default values.

{
  "route": {
    "receiver": "email-example-receiver",
    "groupWait": "30s",
    "groupInterval": "5m",
    "repeatInterval": "4h"
  },
  "receivers": [
    {
      "name": "email-example-receiver",
      "emailConfigs": [
        {
          "to": "your-email@example.com",
          "sendResolved": true
        }
      ]
    }
  ]
}

Afterward, you can check the configuration using the GET Alertconfigs endpoint. You should see a global section as shown below. Attributes masked by ***** indicate that our credentials will be used to send emails.

"global": {
  "resolveTimeout": "5m",
  "smtpFrom": "our-email@example.com",
  "smtpSmarthost": "*****",
  "smtpAuthUsername": "*****",
  "smtpAuthPassword": "*****",
  "smtpAuthIdentity": "*****"
}

How to change your receiver configuration

You can consult the API documentation to learn how to configure and update an existing recipient.

How to read your receiver configuration

To read all your receiver configurations, execute an HTTP GET request using stackit curl:

stackit curl -X GET "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/receivers" \
  -H "accept: application/json"

More information on this can be found in the API documentation.

How to delete your receiver configuration

To delete a specific receiver configuration, execute an HTTP DELETE request to the exact receiver endpoint (replace RECEIVER_NAME with your specific receiver):

stackit curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/alertconfigs/receivers/$RECEIVER_NAME" \
  -H "accept: application/json"