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 

{
  "event": "sync.success",
  "data": {
    "reason": null,
    "deviceFingerprint": {
      "device": {
        "os": {
          "name": "Mac OS",
          "version": "10.15.7"
        },
        "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "cpu": {},
        "agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "device": {
          "model": "Macintosh",
          "vendor": "Apple"
        },
        "engine": {
          "name": "Blink",
          "version": "120.0.0.0"
        },
        "browser": {
          "name": "Chrome",
          "major": "120",
          "version": "120.0.0.0"
        }
      },
      "location": {
        "eu": "0",
        "ip": "41.184.8.12",
        "ll": [
          10,
          8
        ],
        "area": 500,
        "city": "",
        "metro": 0,
        "range": [
          699924480,
          699932671
        ],
        "region": "",
        "country": "NG",
        "timezone": "Africa/Lagos"
      }
    },
    "flow": {
      "id": "0fa34faf-41f1-41b6-baca-1bdd1db32721",
      "reference": "flw_PGnev9Vkxo",
      "name": "Biometric and Document verification 6"
    },
    "metadata": null,
    "verifications": [
      {
        "id": "43600668-7900-406c-811f-de4fd57afee4",
        "reference": "vrf_s7FXLFNBU7",
        "idNumber": "B50383639",
        "firstName": "LUTHFULAHI",
        "lastName": "OSENI",
        "middleName": "OLAITAN",
        "phone": null,
        "email": null,
        "dateOfBirth": "1999-03-31",
        "age": null,
        "sex": "M",
        "country": "NG",
        "nationality": "NGA",
        "issuedDate": null,
        "expiryDate": "2032-11-28",
        "aml": {
          "step": {
            "id": "watchlists",
            "data": [
              {
                "country": "NG",
                "watchlist": {
                  "id": 468,
                  "name": "Banco Interamericano de Desarrollo",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.814Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 455,
                  "name": "US Denied Persons",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.844Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 1221,
                  "name": "HM Treasury Sanctions List",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.856Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 481,
                  "name": "Personas de Interes",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.921Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 463,
                  "name": "Swiss SECO Sanctions",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.922Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 470,
                  "name": "UN Consolidated Sanctions",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.928Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 480,
                  "name": "DEA Most Wanted",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.946Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 439,
                  "name": "INTERPOL Red Notices",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.955Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 1026,
                  "name": "SAT 69B",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.978Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 333,
                  "name": "UK Most Wanted",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:08.992Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 466,
                  "name": "CoE Parliamentary Assembly",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.011Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 471,
                  "name": "US Marshalls Service",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.012Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 437,
                  "name": "US Bureau of Industry and Security",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.013Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 430,
                  "name": "GB Consolidated List of Targets",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.016Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 472,
                  "name": "FBI Most Wanted",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.076Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 469,
                  "name": "EU Members of Parliament",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.094Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 467,
                  "name": "CIA World Leaders",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.095Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 328,
                  "name": "UK Bank of England Sanctions list",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.113Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 1369,
                  "name": "CO SIGEP Informe",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.157Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 1220,
                  "name": "EU Designated Terrorists",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.165Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 458,
                  "name": "US OFAC",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.180Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 1370,
                  "name": "CO SIGEP Declaraciones",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.182Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              },
              {
                "country": "NG",
                "watchlist": {
                  "id": 843,
                  "name": "EU financial sanctions",
                  "watchlistType": "basic"
                },
                "dataSource": "document-data",
                "searchedAt": "2024-01-28T16:35:09.193Z",
                "documentType": "passport",
                "searchParams": {
                  "fullName": "LUTHFULAHI OLAITAN OSENI",
                  "dateOfBirth": "31-03-1999",
                  "documentNumber": "B50383639"
                },
                "searchResult": null
              }
            ],
            "error": null,
            "status": 200
          },
          "flowId": "64db87f07e10b6001ba9ca7d",
          "metadata": {
            "idType": "passport",
            "userId": "9234494b-ad85-4284-8f1f-758faba30828",
            "selfieType": "selfie-photo",
            "selfieVerificationId": "ddfd7737-d722-4aa3-89a5-722bc5b944d8",
            "documentVerificationId": "43600668-7900-406c-811f-de4fd57afee4"
          },
          "resource": "https://api.prod.metamap.com/v2/verifications/65b681aab19f32001d7ba02e",
          "eventName": "step_completed",
          "timestamp": "2024-01-28T16:35:11.940Z"
        },
        "amlRisk": "",
        "address": null,
        "assets": [
          {
            "iso": "NG",
            "url": "https://verisync.s3.us-east-2.amazonaws.com/c94905f7-8e0b-4c2a-ac67-b93411189a53-PassportO.jpg",
            "type": "passport",
            "filename": "PassportO.jpg",
            "stateCode": ""
          }
        ],
        "channel": "web",
        "active": true,
        "message": null,
        "reverifyReason": null,
        "reverifiedAt": null,
        "verifiedAt": "2024-01-29T09:42:21.099Z",
        "deviceFingerprint": {
          "ip": "3.9.13.82",
          "ua": "axios/1.4.0",
          "origin": "",
          "vpnDetectionEnabled": false
        },
        "status": "approved",
        "createdAt": "2024-01-28T16:32:39.760Z",
        "updatedAt": "2024-01-29T09:42:19.845Z",
        "identity": {
          "id": "ae24f21b-2e2d-4d73-ba1a-2eb1fa18b878",
          "reference": "id_jSFK0agbV",
          "name": "International Passport",
          "slug": "passport",
          "description": "Verify your international passport",
          "recomended": true,
          "type": "foundational",
          "category": "document-verification",
          "active": true,
          "status": "approved",
          "createdAt": "2024-01-27T18:04:54.184Z",
          "updatedAt": "2024-01-27T18:04:54.184Z"
        }
      },
      {
        "id": "ddfd7737-d722-4aa3-89a5-722bc5b944d8",
        "reference": "vrf_s5eSoZzvZu",
        "idNumber": null,
        "firstName": null,
        "lastName": null,
        "middleName": null,
        "phone": null,
        "email": null,
        "dateOfBirth": null,
        "age": null,
        "sex": null,
        "country": "",
        "nationality": null,
        "issuedDate": null,
        "expiryDate": null,
        "aml": null,
        "amlRisk": null,
        "address": null,
        "assets": [
          {
            "iso": "",
            "url": "https://verisync.s3.amazonaws.com/05c94f48-e32c-450f-af26-acc86e00372a-selfie_1706459515289.png",
            "type": "selfie-photo",
            "filename": "selfie_1706459515289.png",
            "stateCode": ""
          }
        ],
        "channel": "web",
        "active": true,
        "message": null,
        "reverifyReason": null,
        "reverifiedAt": null,
        "verifiedAt": "2024-01-29T09:42:21.099Z",
        "deviceFingerprint": {
          "ip": "3.9.13.82",
          "ua": "axios/1.4.0",
          "origin": "",
          "vpnDetectionEnabled": false
        },
        "status": "approved",
        "createdAt": "2024-01-28T16:31:58.579Z",
        "updatedAt": "2024-01-29T09:42:21.117Z",
        "identity": {
          "id": "1e94ed1f-be93-42b4-8728-24adbfc495fd",
          "reference": "id_kVRtMXMTvw",
          "name": "Selfie Photo",
          "slug": "selfie-photo",
          "description": "Verify your selfie photo",
          "recomended": false,
          "type": "functional",
          "category": "biometric-verification",
          "active": true,
          "status": "approved",
          "createdAt": "2024-01-27T18:04:54.184Z",
          "updatedAt": "2024-01-27T18:04:54.184Z"
        }
      }
    ]
  }
}

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