Notifications

Please mind, this feature is for activated organizations only.

Receive event notifications with webhooks

VGS now uses webhooks when an event happens in your organization. Available webhook events today are particularly useful for tracking events like when someone changes or updates a live route, or tracking proxy upstream error occurrences.

Begin using webhooks with VGS integration in just three steps:

1. Create a webhook endpoint on your server

2. Add an endpoint in the VGS Dashboard

3. Complete your integration by adding events

Set up instructions

To set up a webhook, go to the Administration section in the left side navigation > Organization Settings > Notifications dashboard page, click Add Notifications on the right to reveal a form to add an endpoint for receiving events.

You can enter any valid and existing URL as the destination for events. After you have added an endpoint, you’ll be able to add/select individual events.

Pick events from the dropdown list, and they will immediately appear in the Events List. Once an event is added to the list, you can set up resources (vaults, users) associated with it. If none is selected, notifications will be triggered for all of them.

List of available notifications events

Manage Webhooks

Existing webhook endpoints can be updated or deleted in the Dashboard’s Notifications section. You also have the option of disabling a webhook endpoint temporarily. VGS does not retry any notifications that are generated while the endpoint has been disabled. For every webhook integration, a unique secret is generated, it is used to verify requests on the client-side.

Webhooks delivery

There are 5 attempts to deliver a webhook; if all of them get non-200 responses, the notification is skipped. Some frequent events like proxy.upstream_error or record.reveal_failed are being grouped to prevent over-spamming. In this case, only 1st, 10th, 100th, 1000th, etc, are being sent for 5-minute time windows. The occurrence field in a webhook payload contains a number of those grouped events.

Webhooks signature

Each webhook request contains a unique signature within the HTTP header vgs-signature to verify the request’s VGS origin.

Example:

vgs-signature:t=1623691785,v0=9370aa8513da0a14d21478f11f039708f7e664bfffebb939f574e57818ce08de

t - UTC timestamp, it must be within a typical 60s delivery time window v0 - request signature itself

The signature is a sha256 hash of a raw request body. Python verification example below:

import hashlib
import hmac
import logging
import time\n\n
TIMSTAMP_DIFF_TOLERANCE = 60\n\n
def check_signature(secret: str, signature: str, body: bytes) -> bool:
    chunks = dict(p.split("=") for p in signature.split(","))
    if abs(int(chunks["t"]) - time.time()) > TIMSTAMP_DIFF_TOLERANCE:
        logging.warning("Timestamp mismatch")
        return False\n
    msg = chunks["t"].encode() + b"." + body
    mac = hmac.new(secret.encode("utf-8"), msg=msg, digestmod=hashlib.sha256)
    if mac.hexdigest() != chunks["v0"]:
        logging.warning("Signature mismatch")
        return False\n
    return True

IP List

The following is a list of IPs that VGS notifications will be arriving from:

• 44.228.126.217

• 50.112.21.217

• 52.24.126.164

• 54.148.139.208

• 2600:1f24:64:8000::/52

• 54.164.207.221

• 54.90.7.123

• 2600:1f28:37:4000::/52

Webhook Integration Limits

Currently, we support only the webhook delivery method, and there is a general limit of 20 integrations per organization. This number can be increased by sending a request to the VGS support team.