Webhooks

Listen to webhook events whenever certain actions occurs

Webhooks allow you to set up a notification system that can be used to receive updates on certain requests made to the Verisync API.

Generally, when you make a request to an API endpoint, you expect to get a near-immediate response. However, some requests may take a long time to process, which can lead to timeout errors. In order to prevent a timeout error, a pending response is returned. Since your records need to be updated with the final state of the request, you need to either:

  • Make a request for an update (popularly known as polling) or,

  • Listen to events by using a webhook URL.

Verify event origin

Since your webhook URL is publicly available, you need to verify that events originate from Verisync and not a bad actor. There are two ways to ensure events to your webhook URL are from Verisync:

  • Signature validation

  • IP whitelisting

Signature validation

Events sent from Verisync carry the verisync-signature header. The value of this header is a HMAC SHA256 signature of the event payload signed using your secret key. Verifying the header signature should be done before processing the event:

const crypto = require('crypto');
const secret = process.env.CLIENT_SECRET;

// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
    if (hash == req.headers['verisync-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event  
    }
    res.send(200);
});

IP whitelisting

With this method, you only allow certain IP addresses to access your webhook URL while blocking out others. Verisync will only send webhooks from the following IP addresses:

  1. 13.42.70.11

You should whitelist these IP addresses and consider requests from other IP addresses a counterfeit.

Whitelisting is domain independent

The IP addresses listed above are applicable to both test and live environments. You can whitelist them in your staging and production environments.

Supported events

These are the possible webhook events you can recieve from verisync

Types of events

Here are the events we currently raise. We would add more to this list as we hook into more actions in the future.

Event
Description

sync.success

A successful synchronization was made

sync.updated

A sync information was updated

sync.processing

A sync initiated successfully and the verifications are still in review

sync.failed

A sync initialization failed

sync.revoked

A sync revoked no more update concerning the sync will be sent

sync.restored

A sync restored more update concerning the sync will be sent

PreviousWebviewNextSync

Last updated