Web Hook Integration Overview

A webhook is an HTTP-based callback function that provides event-driven communication between Konexus and your systems.

In order to receive webhooks, a tenant must create one or more subscriptions. Subscriptions define what event types the tenant would like to receive web hooks for, the URI they wish to receive them on, and the type of security required by that URI. Subscriptions can be created using the Konexus Subscription API.

API Authentication

The Konexus API requires a key for authentication. These keys will be provided by Konexus and are unique for each environment. The key should be added to the request header with the name: x-api-key.

How to use the Subscription API

Subscriptions are created using the Subscription API.  Submitting a POST to the /v2/settings/subscriptions endpoint will create a new subscription.

{  
  "uri": "https://api.staging.Konexus.io/public/v2/settings/subscriptions",
  "security": {
    "x-api-key": "your-konexus-api-key",
    "type": "header"
  },
  "eventTypes": [
    "alert.sent",
    "alert.read"
  ],
  "isActive": true
}

Subscription Security

...
"security": { "type": "none" },
...

...
"security": {
    "apiKey": "my-super-fancy-key",
    "type": "apiKey"
},
...

...
"security": {
    "headers": {
        "X-Client-Id": "my-client-id",
        "X-Client-Token": "my-client-token"
    },
    "type": "header"
},
...

Validating Requests are coming from Konexus

Your application should verify that Konexus is the source of a webhook before responding to the request.  This process aids in protecting sensitive data, as well as securing your application and servers against abuse.

Every request made from Konexus to your application is signed with an HTTP header called X-AlertSense-Signature.  In order to generate this header, Konexus uses the parameters sent in the webhook along with the exact URI that is in your subscription.  The signature uses the HMAC-SHA1 hashing algorithm with your API key as the secret.

Here is how you would calculate the signature and perform the validation on your end:

1. Take the full URI that you specified in your subscription from the protocol (https...) through the end of the query string (everything after the ?).
2. If the request is a POST, sort all of the POST parameters alphabetically.
3. Iterate through the sorted list of POST parameters and append the variable name and value (with no delimiters) to the end of the URL string.
4. Sign the resulting string with HMAC-SHA1 using your API key as the secret.  Remember that your API key's case matters!
5. Base64 encode the resulting hash value.
6. Compare the resultant value to the X-AlertSense-Signature header value in the request.  If they are a match, the request came from Konexus.

Testing a Subscription

Once a subscription has been created, it can be tested by making a GET request to /v2/settings/subscriptions/{id}/test.  This will result in a small request containing only the string "Ping!" being sent to the URI configured in the subscription.  This can be useful for testing security configurations to ensure that web hooks will successfully reach the client endpoint.

Subscription History

Web hook request and response pairs are logged alongside timestamps and other metadata.  This data can be requested at GET /v2/settings/subscriptions/{id}/history.  This can be especially useful during setup of a new subscription when coupled with the testing endpoint.

Retry

Due to the nature of the web, it is presumed that occasionally a request to a client will fail.  To combat this inevitability we have implemented a retry policy.  If a web hook request is sent and we receive anything other than a 2xx response, we will retry the request up to 20 times with an increase of 2 ^ number of attempts in delay on each request up to a maximum delay of 1 hour between requests.

Simple Example

1. A web hook is sent and the client returns a 500 Internal Server Error
2. AlertSense waits 2 ^ 1 seconds (2 seconds)
3. AlertSense retries the web hook and the client returns a 2xx response

Advanced Example

1. A web hook is sent and the client returns a 500 Internal Server Error
2. AlertSense waits 2 ^ 1 seconds (2 seconds)
3. A web hook is sent and the client returns a 500 Internal Server Error
4. AlertSense waits 2 ^ 2 seconds (4 seconds)
5. A web hook is sent and the client returns a 500 Internal Server Error
6. ...
7. AlertSense waits 2 ^ 11 seconds (2048 seconds)
8. A web hook is sent and the client returns a 500 Internal Server Error
9. AlertSense waits 2 ^ 12 seconds (4096 seconds Maximum is 3600 seconds or 1 hour)
10. A web hook is sent and the client returns a 500 Internal Server Error
11. AlertSense waits 2 ^ 13 seconds (8192 seconds Maximum is 3600 seconds or 1 hour)
12. A web hook is sent and the client returns a 500 Internal Server Error
13. ...
14. AlertSense waits 2 ^ 19 seconds (Maximum is 3600 seconds or 1 hour)
15. A web hook is sent and the client returns a 500 Internal Server Error
16. AlertSense waits 2 ^ 20 seconds (Maximum is 3600 seconds or 1 hour)
17. A web hook is sent and the client returns a 500 Internal Server Error
18. AlertSense is unable to send another web hook

Event Types