Webhooks

If you wish to receive notifications outside witboost you can setup 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 by accessing the notifications.webhooks table in the core database.

Each row of the webhooks table represents all the needed details of a webhook to receive notifications.

The webhooks table has the following columns:

• uuid: a UUID that uniquely identifies the webhook within this table.
• url: the target URL that will receive the HTTP POST request with the notification.
• headers: optional list of headers to embed into the HTTP POST request headers section.

To create setup a new webhook, what you have to do is:

1. Generate a UUID v4, you can use uuidgen from your command-line or use any online tool
2. Make an insert SQL statement:

   INSERT INTO
    notifications.webhooks(
      uuid,
      url,
      headers
    )
   VALUES
   (
    '<your UUID v4>',
    '<your webhook URL>',
    '{}'
   )

tip

Optionally, you can leverage Hasura, either with its embedded data editor or by making a GraphQL mutation:

mutation InsertWebhook {
  insert_notifications_webhooks_one(
    object: {
      uuid: "<your generated UUID>"
      url: "<URL where to send the notification>"
      headers: "<optional headers>"
    }
  )
}

Make sure that you are tracking the webhooks table and its relationships inside your Hasura instance, otherwise the above GraphQL mutation won't work.

Next, you have to bind your webhook to the notifications that you wish to receive. To do so, you will need to insert those bindings into the notifications.webhooks_notifications table. These are the steps:

1. Execute this SQL statement:

   INSERT INTO
    notifications.webhooks_notifications(
      webhook_uuid,
      notification_kind,
      enabled
    )
   VALUES
   (
    '<your webhook UUID>',
    '<the notification kind that your webhook should receive>',
    true/false
   )

tip

Optionally, you can leverage Hasura, either with its embedded data editor or by making a GraphQL mutation:

mutation InsertWebhook {
  insert_notifications_webhooks_notifications_one(
    object: {
      webhook_uuid: "<your webhook UUID>"
      notification_kind: "<the notification kind that your webhook should receive>"
      enabled: true/false
    }
  )
}

Make sure that you are tracking the webhooks_notifications table and its relationships inside your Hasura instance, otherwise the above GraphQL mutation won't work.

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 setup 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.