Why use webhooks
Soveren provides you with the nice UI to respond to all sorts of events happening in your infrastructure. However sometimes it is more convenient to use the knowledge about the events in other automation tools like process management or risk management systems. A common example of such system is Security information and event management (SIEM).
A webhook between Soveren and your application tells your application whenever something important happens, so that you don't even need to open the UI and your regular workflow is directly enriched and is up to date.
Configuring the webhook
Creating a webhook is simple and straightforward.
First, open the Integrations in the Soveren app, and press Connect on the Webhook configuration there:
The following configuration panel will open:
Here you need to provide a couple of parameters:
Webhook URL: an endpoint that will be receiving the events.
Token (optional): an optional secret that we should use for signing the request body, if provided. The resulting signature (HMAC-SHA-256) will be present in the
x-soveren-signaturerequest header, e.g.:
We do recommend that you provide the token and check the signature (this protects the webhook from unauthorised use). But if you don't want to then just leave the field blank: the body will not be signed and there will be no additional header in the request.
Now you need to specify what event categories you want to get from the webhook. You can opt for all of them or only for some of them.
After pressing the Save button, make sure you test the connection. If successful, the
200 OK message should appear right next to the Sent test event button:
Using the webhook
Whenever relevant events occur, the webhook will be sending
POST requests to the enpoint that you've provided. The Event object page describes the structure of messages that you will get. You can filter and aggregate on
event_type or on other attributes of the message.
When sending events, Soveren uses the
SoverenWebhook/1.0 user agent. And if you provided the token then there will also be a
x-soveren-signature request header from signing the message body.
Checking the webhook status
If the webhook is working properly, the Integrations in the Soveren app will show the successful connected status:
If Soveren cannot send succesful messages to the webhook endpoint for some time (longer than 15 minutes), then the status will turn into failed: