Volga topics webhooks integration

Volga messages can be forwarded to webhook URLs using the volga-webhook application. The application can be found here: https://www.gitlab.com/avassa-public/volga-webhooks

Permissions

The application needs to have the consume permission for any volga topic it needs to access. For detailed information on how to set up approles and policies, refer to the Programming with Strongbox tutorial.

Basic examples of approle and policy configuration are available in the volga-webhooks repository.

Deployment strategies

Depending on which volga topics you intend to forward you may want to deploy the application to a certain subset of sites, but the two most obvious patterns are:

1. Deploying to all sites and consuming local topics
2. Deploying to a single site and consuming control tower topics

While option 1 is generally simple and perhaps preferable there are valid reasons for going with option 2, for example:

• All edge sites do not have access to the webhook URL
• The wanted topic resides on the control tower only

The volga-webhooks application comes with an example deployment specification that deploys to all sites. To instead deploy to a specific site, just add a condition on system/name or some other label that uniquely identifies the site.

For a list of available system topics, refer to Volga Topics

Configuration

The application is configured by a YAML file defined inside the application specification. Refer to the README.md file for information on specific fields.

Usage examples

Forwarding the entire payload

This is the simplest possible configuration and looks something like this:

webhooks:
 - name: mywebhook
   topic: system:audit-trail-log
   url: "https://hooks.example.com/asdfghjkl"

This will POST the entire payload of every message on system:audit-trail-log to the given URL. To instead subscribe to the audit trail log at the control tower, just add location: parent.

Using jinja2 templates to format POST data

Webhooks may have requirements on the structure of POST data. For example, Slack webhooks require messages to be in JSON format, with the main text contained in a field called text. If your volga messages do not already match this format, you can use a jinja2 template to model the message:

webhooks:
 - name: mywebhook-with-a-template
   topic: system:audit-trail-log
   url: "https://hooks.example.com/asdfghjkl"
   data-template: "{\"text\": \"User {{ user }} accessed {{ path }} at {{ time }}\"}"
   variables:
     - name: user
       path: "payload.user"
     - name: path
       path: "payload.path"
     - name: time
       path: "payload.occurred-at"

The data-template field is a jinja2 template that is rendered using the three variables user, path, and time. The variables are defined in the variables list with each variable pointing out a specific piece of the volga message using JSONPath strings. Note that the variable msg containing the entire message is always available to the template so defining variables is not strictly necessary. The user variable, for example, is just a cleaner way of writing msg['payload']['user'].

Webhook with authentication

The webhook server might require some form of shared secret, in the URL string itself or in an HTTP header. Headers are easily added using the headers list:

   headers:
     - key: MyHeader
       value: SomeValue

Secret tokens or URLS, however, do not belong in the application specification, but should instead be created as secrets and then referd to using variables.

A variable definition could look like this:

    variables:
      - name: TOKEN
        value-from-vault-secret:
          vault: volga-webhooks
          secret: mywebhook
          key: token

And the token can then be used in a header (or URL) without revealing it in the application specification:

   headers:
     - key: Authorization
       value: Bearer ${TOKEN}

See the Secrets Management for further information on managing secrets.