Webhooks

If you wish to receive notifications outside witboost, you can set up a webhook. Webhook is a notification channel that can be used to deliver notifications through an HTTP POST request to a target URL.

Configuring a webhook

Webhooks can be configured through the Administration > Extension Manager page, specifically in the Webhooks tab.

To create a new webhook, click the "Add webhook" button.

You will be required to specify the target URL that will receive the HTTP POST request containing the notification.

After creating a webhook, click on the webhook to enter its detail page.

From here, you have to bind your webhook to the notifications that you wish to receive. To do so, click "Add Trigger" in the Notifications section, and select the notification kind you want to add.

Headers

Through the Headers section, you can also provide an optional list of headers to embed into the HTTP POST request headers section. To add a header, click on "Add header". By clicking on the "key" button next to the header value, you can make the value sensitive. Sensitive values are stored encrypted and will only be decrypted upon notification delivery.

Header constraints

Each header must adhere to the following constraints:

Field	Constraint
Header name	Must start with a letter and must not contain any whitespace or special characters except hyphens
Header name	Must contain at most 128 characters
Header value	Must contain at most 4096 characters

Forwarding user entity fields

By default, the webhook channel will forward a list of user entity references within the notification. Those references can be used to fetch user data from the witboost catalog. However, if you want to receive additional information about users without the need of contacting the witboost catalog, you can provide a set of user entities fields to be retrieved before sending the notification to your webhook's URL.

To set up the fields that you want to receive about a user entity, add the notifications.webhooks.userEntityFields property in your app-config.yaml:

notifications:
  webhooks:
    userEntityFields: [
        'metadata.name',
        'metadata.namespace',
        'kind',
        'spec.email',
      ] # this is just an example of fields that you can parse from a user entity, but this strictly depends on your witboost instance

The resulting user entities, all shaped the same way according to your configuration, will be attached to the webhook notification. If any user reference or configured field results to be invalid or empty, will be filled with a null value. Take a look at the JSON schema to learn more about the shape of these notifications

warning

The payload can get very large if you select a considerable amount of fields and the recipient type has a lot of recipients (e.g. this could happen with the all witboost users recipient type). So pay attention not to overload the notification body. Moreover, if you misconfigured the list of fields, the recipientsEntities field will contain less recipients than the ones listed in the recipients field.

JSON Schema

Your configured webhook is going to receive a POST HTTP request with the following JSON body:

Loading ....

The messages section can be leveraged to send a dedicated text message to a specific audience. If instead you need to craft a different message, you can construct your notification by using the notification body field.

Each notification body is different and can vary among each notification kind. Head to the All notifications section to know about a specific notification body schema.

The recipients field can be enriched with additional user information if you configure what said in the section above: Forwarding user entity fields.