Introduction
Webhooks are a powerful tool that allows Overe to seamlessly communicate with other applications in real time. Essentially, a webhook is a mechanism that sends automated notifications or data to a specified URL when certain events occur within the system. Instead of constantly polling for updates, webhooks let you receive instant alerts when something important happens, like a security breach, a triggered alert, or a user activity that requires your attention.
For users managing complex IT infrastructures or those needing to maintain tight integration with other systems, webhooks can be incredibly useful. They enable you to connect Overe with your existing workflows, such as triggering incident response tools, notifying your team in a chat application, or updating dashboards automatically. This introduction will guide you through the steps to configure webhooks, helping you stay ahead of critical events and maintain the security and efficiency of your environment.
Managing webhooks
Webhooks can be configured at the organization level. This means that we can specify an endpoint were Overe will be pushing notifications for all sites managed under that organization.
Webhooks can be configured into its own section in Organization Config > Notifications > Webhooks
Registering a webhook
In order to register a webhook:
Set up an HTTP endpoint to handle POST requests which is publicly reachable. Find more details about how to achieve a secure implementation in the section Webhook Security below.
Add the public URL for this endpoint in the designated text field in the webhook management screen and click on Register Webhook URI.
A confirmation message should appear if Overe was able to register the webhook, or an error message otherwise.
Removing a webhook
If you want to stop receiving the messages pushed from an Overe organization, you can do so by going back to the webhook management screen and clicking the Clear URI button next to your configured URI.
You should get a result message informing whether the action was successful.
Webhook Security
The following mechanisms have been put in place by Overe to guarantee that both parties are who they claim to be, and have been set up with this purpose of handling notifications.
The registration subscription challenge
This challenge is a string which Overe will send to the specified HTTP endpoint while registering the webhook.
Request issued by Overe
POST https://<endpoint_url>?subscription_challenge=<secret_string>
As a result, the endpoint will need to return the secret string provided as a query parameter, so Overe knows it was expecting this configuration and that the service was set up to process these notifications.
Expected result
Content-Type: application/json
==============================
Body:
{
"subscriptionChallenge": "<string_from_the_query_parameter>"
}
Message signature
With the endpoint correctly configured, you should be ready to process incoming messages.
To make sure that you are only processing requests issued by Overe, all requests will contain a signature you should validate before considering them legit notifications.
Each request issued to the endpoint will include:
POST https://<endpoint_url>
============================
Body:
{ /* notification body */ }
============================
Headers:
Date: <unix-timestamp-seconds-of-the-send-time>
X-Overe-Signature: <notification-signature>
The Date header can be used for replay prevention attacks. You can use that value to implement an initial filter to discard messages which were not issued in a designated tolerance window, so if for any reason a message posted by Overe was intercepted by a man in the middle, it can not be replayed outside the tolerance window.
The X-Overe-Signature header, containing a list of message signatures (in case there are different versions for different algorithms, or because the signing key is being rotated).
Those signature values should be validated against the concatenation the request body contents concatenated with the Date timestamp with a "." separator, using Overe's public keys.
Value to verify against: <body>.<timestamp>
Public Keys
Overe Public Keys, which are needed to validate the messages, can be found in the Overe Portal, in the Webhooks management section, in the Current Configuration panel, once a valid endpoint has been registered.
Example
Here is a Python code that uses the cryptography.io package to verify the signature:
import datetime
import base64
from cryptography.hazmat.primitives.asymmetric import padding, rsa
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes, serialization
def signature_is_valid(signature: str, body: str, date: str, public_key: str) -> bool:
timestamp = datetime.datetime.fromisoformat(date)
unix_timestamp = int(timestamp.timestamp())
signed_body = f"{body}.{unix_timestamp}"
decoded_signature = base64.b64decode(signature)
pubkey = cast(
rsa.RSAPublicKey,
serialization.load_pem_public_key(
public_key.encode(), backend=default_backend()
),
)
try:
pubkey.verify(
decoded_signature,
signed_body.encode(),
padding.PSS(
mgf=padding.MGF1(hashes.SHA256()),
salt_length=padding.PSS.MAX_LENGTH,
),
hashes.SHA256(),
)
return True
except InvalidSignature:
return False
Processing messages
Event notification request follows the CloudEvent specification. The request is a POST request with a JSON payload that contains the event data. The payload is structured as follows:
{
"specversion":"1.0",
"id": "unique-event-guid",
"source": "overe.io",
"type": "webhook.notifications.AnomalyDetected.v1",
"time": "<iso-timestamp-utc>",
"data": {
"message": "<textual message>",
"data": { /* data format specific to the particular event type. */ }
}
}
Event Types
The event types that you should expect are currently:
webhook.notifications.AnomalyDetected.v1: An anomaly has been raised
webhook.notifications.PostureChangeDetected.v1: A change in security posture (increase or decrease) has been detected