Webhooks

When a job is completed, Vouched can post the job results to a defined webhook URL. This can be set as callbackURL in the JS Plugin, the Submit Job or Send Invite API endpoint.

JSON Response

{
            "id": "Pzfsv4FmP",
            "status": "completed",
            "completed": true,
            "accountReviewed": null,
            "submitted": "2022-05-01T22:59:16+00:00",
            "updatedAt": "2022-05-01T22:59:48+00:00",
            "reviewedAt": null,
            "accountGroupSid": "5OkFFH4--",
            "accountId": "wBNItDHMj",
            "reviewSuccess": null,
            "review": null,
            "secondaryPhotos": null,
            "request": {
                "type": "id-verification",
                "callbackURL": "https://your-submitted-callbackURL.com",
                "requestInfo": {
                    "ipaddress": "24.168.30.565",
                    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36",
                    "referer": "http://localhost:3000/"
                },
                "parameters": {
                    "email": "[email protected]",
                    "phone": "111-222-3333",
                    "firstName": "John",
                    "lastName": "Smith"
                },
                "properties": null
            },
            "surveyPoll": null,
            "surveyMessage": null,
            "surveyAt": null,
            "result": {
                "id": "123456",
                "firstName": "John",
                "lastName": "Smith",
                "middleName": "Manthey",
                "dob": "08/22/1980",
                "expireDate": "08/22/2024",
                "issueDate": "09/22/2019",
                "birthDate": "08/22/1980",
                "class": "C",
                "endorsements": "NONE",
                "motorcycle": null,
                "idFields": [
                    {
                        "name": "firstName"
                    },
                    {
                        "name": "lastName"
                    },
                    {
                        "name": "birthDate"
                    },
                    {
                        "name": "class"
                    },
                    {
                        "name": "id"
                    },
                    {
                        "name": "expireDate"
                    },
                    {
                        "name": "issueDate"
                    },
                    {
                        "name": "address"
                    },
                    {
                        "name": "endorsements"
                    },
                    {
                        "name": "lastName"
                    },
                    {
                        "name": "middleName"
                    }
                ],
                "ipAddress": {
                    "city": "New York",
                    "country": "US",
                    "state": "NY",
                    "postalCode": "10010",
                    "location": {
                        "latitude": 30.6279,
                        "longitude": -43.8866
                    },
                    "userType": "residential",
                    "isp": "Spectrum",
                    "organization": "Spectrum",
                    "isAnonymous": false,
                    "isAnonymousVpn": false,
                    "isAnonymousHosting": false,
                    "confidence": 1,
                    "warnings": null
                },
                "aml": null,
                "crosscheck": {
                    "gender": {
                        "man": 3.271,
                        "woman": 0.012
                    },
                    "darkWeb": null,
                    "address": {
                        "errors": [],
                        "warnings": [],
                        "isMatch": true,
                        "isValid": true,
                        "name": "John E Baird",
                        "ageRange": null,
                        "type": "multi-unit",
                        "isForwarder": false,
                        "isCommercial": false
                    },
                    "email": {
                        "errors": [
                            {
                                "type": "NameMatchError",
                                "message": "Name match score is below the threshold (0.9)"
                            }
                        ],
                        "warnings": [],
                        "isMatch": false,
                        "isValid": true,
                        "name": null,
                        "ageRange": null,
                        "isAutoGenerated": false,
                        "isDisposable": false,
                        "daysFirstSeen": 992
                    },
                    "phone": {
                        "errors": [],
                        "warnings": [],
                        "isMatch": true,
                        "isValid": true,
                        "name": "Mr. John M Baird",
                        "ageRange": null,
                        "carrier": "AT&T",
                        "type": "mobile",
                        "isPrepaid": false,
                        "isDisposable": false,
                        "isCommercial": true
                    },
                    "ageRange": {
                        "to": 50,
                        "from": 48
                    },
                    "confidences": {
                        "identity": 0.51,
                        "activity": 0.058,
                        "darkweb": null
                    }
                },
                "gender": {
                    "gender": "man",
                    "genderDistribution": {
                        "woman": null,
                        "man": 3.282
                    }
                },
                "aamva": {
                    "enabled": false,
                    "hasErrors": false,
                    "hasWarnings": false,
                    "createdAt": null,
                    "updatedAt": "2022-05-01T22:59:47+00:00",
                    "status": "Not Applicable",
                    "statusMessage": "AAMVA is not enabled for this account",
                    "completedAt": null,
                    "confidenceScore": null
                },
                "unverifiedIdAddress": [
                    "253 Clinton",
                    "Teaneck , AT 30338-4790",
                    "US"
                ],
                "barcodeData": {},
                "idType": null,
                "ipFraudCheck": {
                    "ipFraud": true,
                    "count": 20,
                    "jobIdList": [
                        "oSYEyNGWr",
                        "RGK0hb5As",
                        "d_yUvbME0",
                        "4yxC7Se44",
                        "23zQ9ERx69",
                        "qAW4985e-",
                        "C15fy7etr",
                        "GAailTNfqQ",
                        "fgiR1IZ27",
                        "KO6WquWZr"
                    ]
                },
                "clientOutput": {
                    "theme": null,
                    "client": null,
                    "capture": {},
                    "includeBarcode": false
                },
                "idAddress": {
                    "streetNumber": "253",
                    "street": "Clinton",
                    "city": "Teaneck",
                    "state": "NY",
                    "country": "US",
                    "postalCode": "34232",
                    "postalCodeSuffix": "3463"
                },
                "geoLocation: {
                    longtitude: 38.8951,
                    latitude: -77.0364,
                    error: null
                },
                "type": "drivers-license",
                "hasPDF417Back": true,
                "hasPDF417Front": null,
                "captureBackId": null,
                "country": "US",
                "state": "NY",
                "confidences": {
                    "id": 1,
                    "idQuality": 0.9015,
                    "idExpired": 1,
                    "idGlareQuality": 1,
                    "idCrosscheckDarkweb": null,
                    "idCrosscheckIdentity": null,
                    "idCrosscheckActivity": null,
                    "birthDateMatch": null,
                    "nameMatch": 0.989,
                    "selfie": null,
                    "selfieSunglasses": null,
                    "selfieEyeglasses": null,
                    "idMatch": 0.989,
                    "faceMatch": null,
                    "barcode": null,
                    "barcodeMatch": null,
                    "idAml": null
                },
                "success": true,
                "successWithSuggestion": true,
                "warnings": false,
                "featuresEnabled": {
                    "aamvaEnabled": false,
                    "aamvaBillable": false,
                    "crosscheckEnabled": false,
                    "crosscheckBillable": false,
                    "darkwebEnabled": false,
                    "darkwebBillable": false,
                    "idvBillable": true,
                    "physicalAddressBillable": true,
                    "ipAddressBillable": true,
                    "faceMatchEnabled": false,
                    "faceMatchBillable": false
                }
            },
            "errors": [],
            "signals": [
                {
                    "category": "id",
                    "message": "Device Info: Macintosh",
                    "type": "deviceInfo",
                    "fields": [],
                    "property": "private"
                }
            ]
        }

Detailed explanation for each field can be found by clicking the 200 Provide Results on Jobs. under the Find Jobs page.

Approved/Rejected properties

In the above JSON response, the main field to check whether a job approved or rejected is result.success. This boolean field indicates Approved when True or Rejected when False.

Approved jobs can still have warnings we recommend checking. The field result.warnings is a boolean that indicates whether there are warnings on the job. If there are warnings, the field result.error can be checked to understand what warnings exactly.

Common warnings are: data-checks/crosscheck error, expired document, DLV error, and AML error.

Validating Webhook Responses

All webhook requests contain X-Signature in request headers. The X-Signature is base64 encoded, created using HMAC-SHA1 using your private key as the key and using the response as data. To validate the webhook response, perform the same signature procedure and confirm that your generated signature matches the sent signature.

📘

If your account uses the signature key, the X-Signature is base64 encoded, created using HMAC-SHA1 with your signature key instead of the private key.

Here is an example of validation from our Node.js sample repo.

AML Monitoring Webhooks

For verification jobs with AML and ongoing monitoring enabled, Vouched is able to post the most recent AML results to a defined webhook URL. This webhook will be triggered when the AML details of a monitored job have changed. This webhook uses the response model from the Retrieve AML Result API endpoint.

To enable AML Monitoring Webhooks, please send the desired callback URL to [email protected].