Webhook Notifications
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:
Create a webhook endpoint on your server
Add an endpoint in the VGS Dashboard
Complete your integration by adding events
Set up instructions
Setting up Notifications in the Vault Dashboard
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.
Setting up Notifications in the CMP Dashboard (preferred)
To set up Notifications in the CMP Dashboard, go Settings > Organization > Notifications.
If your Organization is not enabled for notifications, the dashboard will display a message with guidance to contact support.
If your Organization is enabled for Notifications, the dashboard will display a table view of any existing notifications. Click the "Create new" call to action to kick of the new notification flow.
Clicking into a notification will surface a detailed view of the notification, along with capabilities to edit, delete, and alter the active/inactive status of the notification.
When creating a new notification, or editing an existing event listed for a notification, the user will be prompted to define both the event, as well as its source. Events are sorted into categories according to the product or service it relates to.
Once an event is selected, the user can define the source of the event. Event sources can include CMP accounts, individual vaults/tenants (for which one exists for every CMP account), users, or organizations. Each eligible event source will also denote whether the source exists in a Sandbox, or Live environment.
List of available notifications events
route.created
VAULT
EVERY_SINGLE
route_id
route_name
environment
route.updated
VAULT
EVERY_SINGLE
route_id
route_name
environment
route.delete
VAULT
EVERY_SINGLE
route_id
route_name
environment
vault.created
ORGANIZATION
EVERY_SINGLE
vault_id
vault_name
environment
au_card.updated
EVERY_SINGLE
card_id
old_account_number
old_expiration_date
new_expiration_date
occurred_at
au_card.expired
EVERY_SINGLE
card_id
old_account_number
old_expiration_date
new_expiration_date
occurred_at
au_card.closed
EVERY_SINGLE
card_id
old_account_number
occurred_at
au_card.non_participating
EVERY_SINGLE
card_id
occurred_at
au_card.contact_cardholder_advice
EVERY_SINGLE
card_id
old_account_number
old_expiration_date
occurred_at
au_card.unknown
EVERY_SINGLE
card_id
occurred_at
au_card.enrolled
EVERY_SINGLE
card_id
occurred_at
au_card.opt_out
EVERY_SINGLE
card_id
occurred_at
user.permissions_updated
USER
EVERY_SINGLE
user_email
org_id
list<permission>
user.permissions_deleted
USER
EVERY_SINGLE
user_email
org_id
list<permission>
user.logged_in
USER
EVERY_SINGLE
user_ip
user_email
user.password_updated
USER
EVERY_SINGLE
user_ip
user_email
user.mfa_created
USER
EVERY_SINGLE
user_ip
user_email
user.mfa_deleted
USER
EVERY_SINGLE
user_ip
user_email
proxy.upstream_error
VAULT
EXP_REPEAT
upstream_host
upstream_error
environment
alias.reveal_failed
VAULT
EXP_REPEAT
environment
storage
Managing 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.
Webhook Delivery Schedule
VGS will attempt to deliver a webhook 8 times. If all webhook delivery attempts receive non-200 responses, the webhook delivery will be cancelled. The delivery attempt schedule is detailed below:
Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours (in addition to the previous)
Webhook Grouping
Some frequent events like proxy.upstream_error or record.reveal_failed are grouped to prevent spamming the delivery server. 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.
Webhook Signatures
Each webhook request contains a unique signature within the HTTP header vgs-signature to verify the request’s VGS origin.
Example:
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:
Please note: the 60s timestamp tolerance is very strict. If you require flexibility and/or want to decrease the chance the likelihood of webhook request rejection, it is possible to increase this limit to the allowance you are comfortable with.
Additionally, upon retry, the webhook request will be sent again with the same timestamp. If you have very narrow timestamp 60s, a retry that happens after 30 minutes will be rejected.
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.
Last updated