Webhooks

Webhooks

Webhooks provide a lightweight, event driven method of notifying external systems of events within the MindBridge platform. Internal events 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

Each webhook must have a unique URL. You can configure a webhook to send multiple events to the same URL.
Must be an HTTPS URL.
The URL hostname must use a fully qualified name, not an IP address.

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.

HTTPS Header	Description
`webhook-id`	A unique event ID for the event that triggered the outbound webhook request.
`webhook-timestamp`	Timestamp associated with the outbound HTTPS request.
`webhook-signature`	The digital signature that can be used to validate the authenticity of the webhook data.

Security

Webhooks operate by communicating with configured HTTPS URLs. This can lead to potential security risks from malicious actors. To authenticate the validity of webhook payloads on the receiving side, the MindBridge platform implements an asymmetric digital signature scheme. This scheme verifies that a payload originated from the platform and has not been modified. When a webhook is registered, a public key utilizing the Ed25519 algorithm is associated with the webhook configuration. Measures used to mitigate common attack scenarios within the digital signing scheme are 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.

HTTP Code	Result
200 series response	Successfully received webhook payload

Authenticating a Payload

Use the data from the payload, the headers in the HTTP post, and the public key associated with your webhook configuration. With these, 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.

Variable	Description
webhook-id	Found in the HTTP header
webhook-timestamp	Found in the HTTP header
payload	The unmodified contents of the HTTP POST request

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

Name	Description	Event Type	Payload Model
Analysis Created	Notify the registered webhook URL that an Analysis has been created.	analysis.created	AnalysisWebhookPayload
Analysis Updated	Notify the registered webhook URL that an Analysis has been updated.	analysis.updated	AnalysisWebhookPayload
Analysis Deleted	Notify the registered webhook URL that an Analysis has been deleted.	analysis.deleted	AnalysisWebhookPayload
Analysis Archived	Notify the registered webhook URL that an Analysis has been archived.	analysis.archived	AnalysisWebhookPayload
Analysis Unarchived	Notify the registered webhook URL that an Analysis has been unarchived.	analysis.unarchived	AnalysisWebhookPayload
Analysis Complete	Notify the registered webhook URL that an analysis has been completed.	analysis.complete	AnalysisWebhookPayload
Analysis Failed	Notify the registered webhook URL that the Analysis has failed.	analysis.failed	AnalysisWebhookPayload
Engagement Created	Notify the registered webhook URL that an Engagement has been created.	engagement.created	EngagementWebhookPayload
Engagement Updated	Notify the registered webhook URL that an Engagement has been updated.	engagement.updated	EngagementWebhookPayload
Engagement Deleted	Notify the registered webhook URL that an Engagement has been deleted.	engagement.deleted	EngagementWebhookPayload
Unmapped Accounts	Notify the registered webhook URL that an engagement has unresolved account mappings that exist, which is the result of new accounts discovered during a data ingestion workflow.	unmapped.accounts	EngagementWebhookPayload
Ingestion Complete	Notify the registered webhook URL that a data ingestion workflow has been completed.	ingestion.complete	AnalysisSourceWebhookPayload
Ingestion Failed	Notify the registered webhook URL that a data ingestion workflow has been completed.	ingestion.failed	AnalysisSourceWebhookPayload
Data Added	Notify the registered webhook URL that new data has been added to an engagement.	data.added	FileManagerWebhookPayload
Export Ready	Notify the registered webhook URL that a requested file export has been completed.	export.ready	FileManagerWebhookPayload
User Invited	Notify the registered webhook URL that a User has been invited to the tenant.	user.invited	UserRoleWebhookPayload
User Role Updated	Notify the registered webhook URL that a User’s role has been updated.	user.role	UserRoleWebhookPayload
User Deleted	Notify the registered webhook URL that a User has been deleted.	user.deleted	UserWebhookPayload
User Login	Notify the registered webhook URL that a User has logged in.	user.login	UserLoginWebhookPayload
User Status Updated	Notify the registered webhook URL that a User has been enabled or disabled.	user.status	UserStatusWebhookPayload

WEBHOOK

webhooks

{
  "eventId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "senderId": "<string>",
  "tenantId": "<string>",
  "userId": "<string>",
  "data": {
    "eventId": "<string>",
    "analysisId": "<string>",
    "analysisResultId": "<string>",
    "engagementId": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

webhook-id

string

required

A unique event ID for the event that triggered the outbound webhook request.

webhook-timestamp

integer<int32>

required

Timestamp associated with the outbound HTTPS request.

webhook-signature

string

required

The digital signature that can be used to validate the authenticity of the webhook data.

Body

application/json

type

enum<string>

The event type that triggered the webhook.

Available options:

analysis.complete,

analysis.failed

eventId

string

The ID of the event that triggered the outbound request.

timestamp

string<date-time>

The time that the webhook was triggered.

senderId

string

The ID of the registered webhook configuration that initiated the outbound request.

tenantId

string

The name of the tenant that triggered the webhook.

userId

string

The ID of the user that initiated the event that triggered the webhook.

data

object

The data associated with the webhook event.

Show child attributes

⌘I

{
  "eventId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "senderId": "<string>",
  "tenantId": "<string>",
  "userId": "<string>",
  "data": {
    "eventId": "<string>",
    "analysisId": "<string>",
    "analysisResultId": "<string>",
    "engagementId": "<string>"
  }
}

Overview

Details

API reference

Webhooks

URL Restrictions

Outbound Request

Security

Configuring your Server

Responding to Webhook Requests

Authenticating a Payload

Events

Authorizations

Headers

Body