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	An analysis was created.	analysis.created	AnalysisWebhookPayload
Analysis Updated	An analysis was updated.	analysis.updated	AnalysisWebhookPayload
Analysis Deleted	An analysis was deleted.	analysis.deleted	AnalysisWebhookPayload
Analysis Archived	An analysis was archived.	analysis.archived	AnalysisWebhookPayload
Analysis Unarchived	An analysis was unarchived.	analysis.unarchived	AnalysisWebhookPayload
Analysis Complete	An analysis completed successfully.	analysis.complete	AnalysisWebhookPayload
Analysis Failed	An analysis failed.	analysis.failed	AnalysisWebhookPayload
Engagement Created	An engagement was created.	engagement.created	EngagementWebhookPayload
Engagement Updated	An engagement was updated.	engagement.updated	EngagementWebhookPayload
Engagement Deleted	An engagement was deleted.	engagement.deleted	EngagementWebhookPayload
Unmapped Accounts	An engagement has unresolved account mappings from accounts discovered during ingestion.	unmapped.accounts	EngagementWebhookPayload
Ingestion Complete	A data ingestion workflow completed.	ingestion.complete	AnalysisSourceWebhookPayload
Ingestion Failed	A data ingestion workflow failed.	ingestion.failed	AnalysisSourceWebhookPayload
File Added	A file was added through the file manager.	file.added	FileManagerWebhookPayload
Connection Data Complete	Asynchronous connection data work finished (for example reading table data).	connection.data.complete	ConnectionAsyncWebhookPayload
Connection Test Complete	An asynchronous connection test finished.	connection.test.complete	ConnectionAsyncWebhookPayload
Connection Created	A connection was created.	connection.created	ConnectionLifecycleWebhookPayload
Connection Deleted	A connection was deleted.	connection.deleted	ConnectionLifecycleWebhookPayload
Export Ready	A requested file export is ready for download.	export.ready	FileManagerWebhookPayload
User Invited	A user was invited to the tenant.	user.invited	UserRoleWebhookPayload
User Role Updated	A user’s role was updated.	user.role	UserRoleWebhookPayload
User Deleted	A user was deleted.	user.deleted	UserWebhookPayload
User Login	A user logged in.	user.login	UserLoginWebhookPayload
User Status Updated	A user was enabled or disabled.	user.status	UserStatusWebhookPayload
MCP Admin Settings Updated	Tenant MCP admin settings changed. See the Activity Report for details.	mcp.admin-settings.updated	McpAdminSettingsWebhookPayload

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