Intro

VersionVault Express can be configured to send out notifications when interesting events happen inside projects. These notifications are called webhooks. A webhook is simply a JSON payload sent to an endpoint over HTTP as a POST request. Any system that can respond to an HTTP POST request can be a webhook endpoint and perform any action it so chooses. In this article we will look at basic information related to webhooks. Creating and updating webhook definitions requires the user have Builder role in the project. For information about roles, refer to Project Team Member Roles in VersionVault Express blog.

Project vs. stream webhooks

VersionVault Express allows users to create webhooks with a context of either the project or an individual stream in the project. The implementation of webhook firing is identical for all webhooks; the difference between project and stream webhooks is which underlying events will cause the webhook to fire. Creating a project webhook is done via the webhook page under the project settings page, while creating a stream webhook is done via the webhook page (navigated to on a per stream basis)  under the primary stream page. Whether a project or a stream webhook is being created, you will  be able to create a first webhook:

 

Webhook definition screen

The create webhook window is identical for project and stream webhooks except for the events which can be selected.

The create webhook screen is shown above. The active slider in the upper right corner indicates whether the webhook will fire. It may be desirable to stop webhooks from firing without removing the definition of the webhook. By default the webhook will fire.

Webhook name

The webhook name is an identifier for the webhook.

Payload URL

The payload URL is the defined endpoint which will respond to the request. The payload URL should accept an HTTP request with a JSON body and perform whatever actions are needed based on the payload.

Secret

The secret will add a hash based on the payload contents into the HTTP header for the webhook.

Event type Firing condition
Join project When an invited user has either accepted an invitation to join a project or the user has access the project for the first time. Good to keep track of users activity.
Create stream When a user has created a new stream on the project. This fires both when a user explicitly creates a new stream or joins the project and VersionVault Express creates a new stream implicitly.
Update VOB ACL When a user has been added or removed from a project.

The event types for stream webhooks:

Event type Firing condition
Deliver When a user has completed the deliver of a set of activities to an integration stream. The webhook is defined on the integration stream. Good for initiating builds on the integration stream.
Request build When a user has explicitly requested a build on the specified stream via the main stream page. Good for developers to test their builds on development streams pre-delivery.
Recommend Baseline When a user has recommended a baseline on the specified stream. Good for notifying users that a baseline is a good one for rebasing.
Make baseline When a user has created a baseline on the specified stream.
Create stream When a user has created a development stream based off the parent integration stream. The webhook is defined on the parent stream.
Rebase When a user has completed a rebase from the parent integration stream. The webhook is defined on the development stream.

Webhook payloads

Each webhook contains different information useful to the event which triggered the webhook. See our blog page for complete payload information.

Disable SSL validation

By default, server certificates are checked against available certificate authorities. Select this option to bypass validation if needed.

Webhook firing

When a webhook is fired, an HTTP request is sent to the endpoint.  The Content-Type in the header will indicate application/json. The body of the request is a JSON representation of the payload and contains the payload contents. A sample payload is shown below with the fields common to all webhook payloads.

 

If the secret had been specified during webhook creation, an additional header will be added to the HTTP request containing a hash value of the payload and secret as below:

X-VV-Signature : sha256=866c3800b398bd8c97a575268b2dea7b6adc329a3052ffec140572ed86e61b1f

This signature can be recreated by an endpoint that knows the secret to confirm the payload has not been modified. Refer to our blog site for a detailed example on setting up an endpoint.

On sending the HTTP request, the send will wait up to 60 seconds to establish a connection with the specified endpoint, and once connected, up to 20 seconds to receive a reply from the endpoint. It’s important that the endpoint respond in a meaningful way to the request. The server will take action based on the response from the endpoint as follows:

  • If the endpoint replies with a valid response: the headers, body, response code, and response text will be retrieved and stored as a delivery record for the webhook. This delivery record can be retrieved to see the status of the webhook delivery attempt.
  • If the endpoint does not reply, or replies with a 400 series HTTP code: the webhook will be retried. In this case, the delivery record is updated with the failure condition and a new request will be resent after 60 seconds. This retry cycle will repeat three times (for a total of three minutes). If all retries fail to send the webhook and receive an accepted status, no more attempts will be retried for this instance of the webhook firing. Status information on the failed attempts can be obtained from the webhook information screen.
  • If an endpoint is configured that never receives: the webhook payload will be sent four times.

Webhook delivery records

Each webhook maintains a record of the status of the delivery attempts. Examination of these records via the VersionVault Express UI may indicate problems reaching an endpoint, a problem in the endpoint, or even success in rare instances.

Summary

Webhooks are a powerful way to trigger actions based on different events occurring in VersionVault, whether initiated by VersionVault Express or the VersionVault Explorer desktop client. With proper development of an endpoint to receive and process the payloads, the integration possibilities are endless.

 

 

 

 

 

Comment wrap
Further Reading
article-img
Secure DevOps | April 29, 2022
Installing VersionVault Express on AWS
The blog aims to create a zero to fully working instance of VersionVault Explorer on AWS. The assumption is that the reader has a valid credential on AWS with permission to EC2 and S3 on an admin level. We also presume, the user has his initial setup in place and can take off with the installation with the instructions that follow.
article-img
Secure DevOps | January 13, 2022
Comparing file in VersionVault Express
VersionVault Express features an intuitive side-by-side comparison viewer where you can easily compare files and directories. VersionVault Express not only allows you to compare elements against their immediate predecessor but also to compare them against the changeset predecessor.
article-img
Secure DevOps | January 12, 2022
How to automatically create webhooks on new streams
In this article we’ll look at one such extension and show how to automatically give newly created streams the ability to request builds.
Close
Filters result by
Sort:
|