Webhook basics
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.
