Webhooks

Webhooks provide a lightweight, event driven method of notifying external systems of events within the MindBridge platform, enabling internal events to communicate data with external systems via HTTPS requests originating from our platform, allowing for a more robust automation potential, without the need to poll for status. In order to leverage webhook functionality, a URL must be provided, and a selection of events that you would like to receive notifications for associated with that URL.

URL Restrictions

• URL defined must be unique.
• Protocols are limited to https.
• IP addresses are not permitted.
• Domains that resolve to local ip addresses.
• Unqualified hosts are not permitted (domains without a . in them).
• Domains ending in .local, .azure.com, microsoft.net, mindbridge.ai, mindbridge.com are not allowed (this list is subject to change, as additional restrictions may be introduced in the future).

Outbound Request

Each outbound request is sent as an HTTPS POST. The post will contain a JSON payload in the body of the message. As well as the JSON payload, there are a number of important HTTPS headers that are attached to each message. Using this information, combined with the public key associated with the configured webhook, allows the verification of a digital signature. The method of authenticating the payload will be covered in a separate section.

Security

Webhooks operate by communicating with user provided HTTPS URLs. This can lead to potential security risks from malicious actors. In order to provide a way to authenticate the validity of the webhook on the client side, we have implemented an asymmetric digital signature scheme that can be used to check that the payload is from us, and has not been modified. When a webhook is registered within our system, clients are provided with a public key, which utilizes the Ed25519algorithm. There are a number of measures used to avoid common attack scenarios within the digital signing scheme, which will be covered below.

Configuring your Server

In order to listen to webhook events, you must have a publicly accessible server that can accept HTTPS POST requests from the MindBridge system. This server must not implement any authentication protocols in order to receive data. The data signature scheme implemented provides a mechanism to ensure data integrity, and while this is optional to authenticate the received payload, it is highly recommended to utilize this data integrity check in your workflow.

Responding to Webhook Requests

How you respond to a webhook event has implications on the status of the webhook configured within the MindBridge system. We look at the HTTP response code, and in some cases the HTTP headers in order to determine actions we may take within our system.

Authenticating a Payload

Utilizing the data from the payload, as well as the headers in the HTTP post, as well as the public key associated with your webhook configuration, you will be able to validate the digital signature that is attached in the HTTP header. In order to accomplish this, you need to format a string with the following format:

<webhook-id>.<webhook-timestamp>.<payload>

Values with < > surrounding them are variables to insert into the template above.

With this string generated, and using the public key from the webhook configuration, and the algorithm Ed25519, you can create a digital signature of the formatted string created above, and compare it against the digital signature provided in the HTTP header, under the key webhook-signature. The creation of this formatted payload helps to mitigate common attack patterns, such as replay attacks, which is why the timestamp of the outbound request is part of the signed message.

Events