Web Hook Integration

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"
},
...

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