Skip to main content
API docs by Redocly

Webhook Notifications API (0.1.0)

Overview

By implementing the Webhook Notifications API, you will be able to receive notifications about events happened within the Witboost platform.

The Webhook Notifications API is helpful for integrating with third-party messaging systems like Microsoft Teams, Slack, Discord etc.

Your configured webhook URL will receive a POST request with a JSON payload representing a notification.

Notification Body

The body field of the notification payload is a free-form object whose structure depends on the kind of the notification. Each notification kind defines its own body schema.

Messages

The payload includes a messages array containing pre-built messages, each targeted to a specific audience (recipient type). Witboost provides a suggested title and message for each audience, but you are free to ignore them and compose your own custom message using the fields available in the notification body.

The responsibility of your webhook service is to deliver a message to each recipient, treating them according to their recipient type. This means the service should send personalized messages based on the audience (e.g. a system owner may receive a different message than the requester).

Recipient Types

Each message includes a recipientType (legacy) and recipientType_v2 (new) field indicating the target audience. The recipientType_v2 field was introduced to avoid breaking changes for new recipient types from team roles and glossary renaming.

Note: in the legacy field, recipient-type:project-data-access-manager is mapped to recipient-type:system-owner for backward compatibility.

Recipients

By default, each recipient object contains only the userRef field (the user entity reference as known by witboost).

However, recipients can be enriched with additional user entity fields (e.g. metadata.name, spec.email, kind) by configuring the notifications.webhooks.userEntityFields property in app-config. When configured, the specified fields are resolved from the user entity catalog and attached to each recipient object. If a user reference or a configured field is invalid or empty, it will be filled with a null value.

See Forwarding user entity fields for details.

Notification Schemas

The complete list of notification kinds and their respective body schemas can be consulted either in the Notifications section of the documentation or directly from Witboost > Administration Panel > Developer Tools > Notification Schemas.

Receive a notification

Endpoint invoked by Witboost to deliver a notification to your webhook.

Request Body schema: application/json
required

The webhook notification payload containing the notification kind, body, messages for each audience, and metadata.

kind
required
string

The notification kind identifier (e.g. notification:access-control-request-failed).

sender
required
string

The sender of the notification.

required
object

Free-form object whose structure depends on the notification kind. Refer to the Notifications documentation for the schema of each kind.

required
Array of objects (NotificationMessage)

List of pre-built messages, each targeted to a specific audience (recipient type). Witboost provides a suggested title and message for each audience, but you are free to ignore them and compose your own custom message using the fields available in the notification body.

The responsibility of the webhook service is to deliver a message to each recipient, treating them according to their recipient type. This means the service should send personalized messages based on the audience (e.g. a system owner may receive a different message than the requester).

required
object (NotificationMetadata)

Responses

Request samples

Content type
application/json
{
  • "kind": "notification:access-control-request-failed",
  • "sender": "platform:witboost",
  • "body": {
    },
  • "messages": [
    ],
  • "metadata": {
    }
}