Webhook alert channel

Learn about sending alert notifications by using webhook.

To send alert notifications by using webhook, create a webhook alert channel.

Creating a webhook alert channel

Use the Instana UI to create a webhook alert channel.

Click Settings > Global settings > Events & alerts > Alert channels > Add alert channel > Generic webhook. The Webhook URL format is protocol://domainOrIPAddress:port/path.

webhook alert channel

After you provide all the parameters, click Test channel to check whether the webhook domain is allowed for outbound traffic. If you see an error message similar to the following message, it means that the domain is not allowed for egress traffic. To resolve the issue, contact Instana support. For more information, see Why am I not receiving alerts for my webhook alert channel?.

Test Failed
Test alert could not be sent to Generic webhook alert channel because the domain is currently not allowed for security reasons. Please contact Instana support to allow this domain.

Alerting examples

The following Webhook events are received as an HTTP POST to the configured URLs (HTTP or HTTPS):

In the following examples, the Instana Webhook format is used. The Instana Webhook format is not compatible with third-party tools that expect an Incoming Webhook in their format. You might want to use a custom-made adapter or If This Then That to connect to third-party tools.

On open issues or incidents

{
  "issue": {
    "id": "53650436-8e35-49a3-a610-56b442ae7620",
    "type": "issue",
    "state": "OPEN",
    "start": 1460537793322,
    "severity": 5,
    "text": "Garbage Collection Activity High (11%)",
    "suggestion": "Tune your Garbage Collector, reduce allocation rate through code changes",
    "link": "https://XXXXXXX/#/?snapshotId=rjhkZXdNzegliVVEswMScGNn0YY",
    "zone": "prod",
    "fqdn": "host1.demo.com",
    "entity": "jvm",
    "entityLabel": "Test jvm",
    "tags": "production, documents, elasticsearch",
    "container": "test-container"
  }
}

On close issues or incidents

{
  "issue": {
    "id": "53650436-8e35-49a3-a610-56b442ae7620",
    "type": "issue",
    "state": "CLOSED",
    "start": 1460537793322,
    "end": 1460538393322,
    "severity": 5,
    "text": "Garbage Collection Activity High (11%)",
    "suggestion": "Tune your Garbage Collector, reduce allocation rate through code changes",
    "link": "https://XXXXXXX/#/?snapshotId=rjhkZXdNzegliVVEswMScGNn0YY",
    "zone": "prod",
    "fqdn": "host1.demo.com",
    "entity": "jvm",
    "entityLabel": "Test jvm",
    "tags": "production, documents, elasticsearch",
    "container": "test-container"
  }
}

On change events

{
    "issue": {
        "id": "G9KRvijARFw6vffuygCvl_Fyg",
        "type": "change",
        "start": 1743798954000,
        "text": "Change detected",
        "description": "The value has changed from X to Y.\n",
        "link": "https://X/#/events;eventId=G9KRvijARFw6vffuygCvl_Fyg?&snapshotId=mTraati8sdfl0H5qrEagmIRIBYoM4",
        "end": 1743798954000,
        "zone": "prod",
        "fqdn": "something.com",
        "entity": "Kubernetes Pod",
        "entityLabel": "Test",
        "tags": "docs",
        "container": "b-container"
        }
    }
}

On offline, online events

{
  "issue": {
    "id": "53650436-8e35-49a3-a610-56b442ae7620",
    "type": "presence",
    "start": 1460537793322,
    "text": "online",
    "description": "Java virtual machine on Host host1.demo.com",
    "link": "https://XXXXXXX/#/?snapshotId=rjhkZXdNzegliVVEswMScGNn0YY",
    "zone": "prod",
    "fqdn": "host1.demo.com",
    "entity": "jvm",
    "entityLabel": "Test jvm",
    "tags": "production, documents, elasticsearch",
    "container": "test-container"
  }
}

On agent monitoring events

{
    "issue": {
        "id": "ah7cCh99TjGqnZJ4UL-uZHA",
        "type": "monitoringIssue",
        "state": "OPEN",
        "start": 1743798151988,
        "severity": 5,
        "text": "Monitoring issue: nodejs_collector_not_installed",
        "suggestion": "Our Agent observed a problem with monitoring the linked process.",
        "link": "https://XX/#/events;eventId=ah7cCh99TjGqnZJ4UL-uZHA?&snapshotId=UhgAKBptVGeu04DsagNGU",
        "zone": "ava",
        "fqdn": "cool.fyre.ibm.com",
        "entity": "Process",
        "entityLabel": "node  (7532267)",
        "tags": "proc",
        "container": "c-container"
    }
}

HTTP request headers

Providing custom HTTP request headers

Some Webhook integrations need the specification of additional Headers that can be added in this section. An example is the addition of an API token for AWS API Gateway.

Webhook URL basic authentication

As an alternative to providing the respective Authorization HTTP request header manually, you can use HTTP basic authentication via the webhook URL. By prepending username and password to the hostname, such as https://username:password@webhookurl.com, the credentials are automatically Base64-encoded and provided as the following HTTP header value:

Authorization: Basic <base64 encoded credentials>

FAQ

Why am I not receiving alerts for my webhook alert channel?

By default, no egress traffic is allowed for any webhook domain due to strict security requirements. When you create a webhook alert channel, you must allow outgoing traffic to the specific domain or URL of the webhook receiver so that the alert notifications are sent successfully to the webhook endpoint.

Contact Instana support to get the domain added to the allowed list.

How can I ensure that the Instana backend can establish a TCP/TLS connection?

The Instana backend are issuing requests from AWS/Google Cloud servers. Therefore, it is important that the JavaScript and source map files are generally accessible from the internet. Additionally, make sure that your backend has a working TLS configuration with a complete certificate chain. You can check for any TLS issues by using the free SSL Test from SSL Labs/Qualys or by running the following command:

openssl s_client -showcerts -connect {{YOUR_DOMAIN_HERE}}:443