Webhooks
Use webhooks to get notified about reports that happen in your YVOS account.
At Youverify, webhooks are a very important part of our reporting process. We use webhooks to communicate with different services. These are our identity and address services.
Webhooks get pushed when the address or identity has been completed.
Please follow the following steps to have access to it;
▪ Set your webhook from the YVOS web portal(If already set, ignore the next step).
▪ Login to the YVOS portal-->Go to settings -> API KEY/Webhook. Scroll to " Webhook" and set your HTTP callback URL.
It is of great importance to verify that an event originated from Youverify to avoid delivering value based on a fictitious event.
Validate the Signature - Valid events are raised with a header x-youverify-signature which is essentially a HMAC SHA512 signature of the event payload signed using your secret key.
The status report “PENDING” for our Identity services is displayed when our upstream identity providers are unavailable.
This status enables us to manage the upstream provider's downtime. To get the completed result for verification with a “PENDING” status, you will have to listen to the webhook to retrieve the completed verification and the corresponding response. The sample below shows when an identity verification request with a “PENDING” status.
PENDING REQUEST IDENTITY RESPONSE PAYLOAD
{
"data": {
"id": "reports_7cf70262-0e6d-47fd-9792-9da167db2c6a",
"reference_id": "5c9260b8f2e11",
"candidate": {
"id": "c3cc9392-ee0d-4c8d-b78b-599dbbaba238",
"reference_id": "YV5c9260b7ac780",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"middle_name": "",
"email": null,
"mobile": null
},
"status": "PENDING",
"reason": "Pending Request",
"identity_number": "AAA26887AA01",
"package": "identity",
"package_name": "Identity",
"type": "frsc | nin | bvn | ibvn | pvc",
"task_created_by": "Youverify Devops",
"end_time": "2019-03-20 16:48:09"
},
The information below is sample post data to your registered webhook for identity verification, for a verified and not verified report.
Identity response:
{
'data': {
'id' : 'reports_424380ae-5e6a-425b-abcb-24e082e4a7a5',
'status' : 'NOT VERIFIED | VERIFIED',
'task_status' : 'NOT VERIFIED ' | 'VERIFIED',
'reason' : 'Invalid application details.',
'package_name' : 'Identity',
'candidate_id' : 3388,
'package' : 'identity',
'identity_type' : 'frsc | nin | bvn | ibvn | pvc',
'identity_number' : 22122122221
}
};
ADDRESS RESPONSE PAYLOAD
Address Completed Payload(individual) v2
Address Completed Payload(Guarantor) v2
Address Completed Payload(business) v2
{
"event": "address.completed",
"apiVersion": "v2",
"data": {
"candidate": {
"candidateId": "620861ac0972f71ec8caf07d",
"firstName": "Famous",
"middleName": "Prior",
"lastName": "Ehichioya",
"photo": "https://youverify-api-bucket.nyc3.digitaloceanspaces.com/reports/live_photos/2022-02-13/photo_620845a0edc7b3471.jpg",
"email": "[email protected]",
"mobile": "08030000000"
},
"agent": {
"firstName": "Famous",
"middleName": null,
"lastName": "Ehichioya",
"signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQE",
"photo": "https://api.staging.youverify.co/uploads/agents/images/c0806491bf8e74bf1fc06d9e2949408e6f957249.jpg"
},
"address": {
"latlong": {
"lat": "6.5009833",
"lon": "3.376612"
},
"flatNumber": "1st floor",
"buildingName": "Sum house",
"buildingNumber": "350",
"subStreet": "Hughes avenue",
"street": "Borno way",
"landmark": "Police Station",
"state": "Lagos",
"city": "Yaba",
"country": "Nigeria",
"lga": "Lagos Mainland"
},
"referenceId": "620865a2cae6f",
"parentId": null,
"status": "awaiting_qa",
"taskStatus": "VERIFIED",
"subjectConsent": "true",
"startDate": "2022-02-13T00:00:00.000Z",
"endDate": "2022-02-13T00:00:00.000Z",
"submittedAt": "2022-02-13T02:20:03.000Z",
"executionDate": "2022-02-13T02:20:03.000Z",
"completedAt": "2022-02-13T02:20:03.000Z",
"acceptedAt": "2022-01-06T07:47:27.000Z",
"revalidationDate": "2022-05-13T00:00:00.000Z",
"notes": [
{
"createdAt": "2022-02-13 03:20:02",
"note": "Candidate resides at Flat Number 1st Floor, Sum House, 350, Sub Street Hughes Avenue, Borno Way Street, Police Station, Yaba, Lagos, Nigeria, . It is a Terraced house painted black with a yellow gate. Address and candidate was confirmed by the Nearby retailer"
}
],
"isFlagged": true,
"agentSubmittedLongitude": "3.3808834",
"agentSubmittedLatitude": "6.490806",
"reportGeolocationUrl": "https://www.google.com/maps/search/?api=1&query=6.490806, 3.3808834",
"mapAddressUrl": "https://www.google.com/maps/search/?api=1&query=350+Borno+Way%2C+Yaba+%2C+Lagos%2C+Nigeria",
"submissionDistanceInMeters": 1226,
"reasons": null,
"signature": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQE",
"images": [
{
"filePath": "https://youverify-api-bucket.nyc3.digitaloceanspaces.com/reports/files/images/resize/2022-02-13/1644718659252.jpg",
"fileType": "image/jpg",
"height": 300,
"width": 400
}
],
"buildingType": "Terraced house",
"buildingColor": "black",
"gatePresent": true,
"gateColor": "yellow",
"availabilityConfirmedBy": "Nearby retailer",
"closestLandmark": "House",
"additionalInfo": null,
"reportAgentAccess": null,
"incidentReport": null,
"description": "Verify the candidate",
"reportId": "reports_4768505a-f96b-42f0-a53e-310aada37a81",
"downloadUrl": "https://api.staging.youverify.co/v1/reports/reports_4768505a-f961-42f0-a53e-310aada37a81/download/pdf",
"apiVersion": "v2",
"businessType": "admin",
"businessId": "61d880f1e8e15aaf24558f1a",
"userId": "61d880f2e8e15aaf24558f9b",
"type": "individual",
"metadata": {},
"createdAt": "2022-02-13T01:58:07.159Z",
"_createdAt": "2022-02-13T02:58:077+01:00",
"verificationId": "620865a2cae6f",
"id": "620865980972f71ec8caf080"
}
}
{
"event": "address.completed",
"apiVersion": "v2",
"data": {
"candidate": {
"candidateId": "61d88528e8e15aaf249fe191",
"firstName": "Famous",
"middleName": null,
"lastName": "Ehichioya",
"photo": "https://cdn.youverify.co/1640838946220-r6fvnt3g0YDgxYikH9e1y.png",
"email": "[email protected]",
"mobile": "08129xxxxxx"
},
"guarantor": {
"firstName": "Peter",
"middleName": null,
"lastName": "James",
"photo": null,
"email": "[email protected]",
"mobile": "080xxxxxxxx"
},
"agent": {
"firstName": null,
"middleName": null,
"lastName": null,
"signature": null,
"photo": null
},
"address": {
"latlong": {
"lat": "0",
"lon": "0"
},
"flatNumber": null,
"buildingName": null,
"buildingNumber": null,
"subStreet": null,
"street": null,
"landmark": null,
"state": null,
"city": null,
"country": "Nigeria",
"lga": null
},
"referenceId": "5b17c55a24328",
"parentId": null,
"status": "completed",
"taskStatus": "VERIFIED",
"subjectConsent": "true",
"startDate": "2018-06-06T00:00:00.000Z",
"endDate": "2018-06-06T00:00:00.000Z",
"submittedAt": "2018-06-06T13:28:26.000Z",
"executionDate": "2018-06-06T13:28:26.000Z",
"completedAt": null,
"acceptedAt": null,
"revalidationDate": null,
"notes": [
{
"note": "He leaves in 3rd room by the left, bungalow painted green but fading already, there is a mosque beside the house, a female tailor who is a tenant sows females cloths at the front.",
"createdAt": "2018-06-07T15:50:33.000Z"
}
],
"isFlagged": false,
"agentSubmittedLongitude": "3.3196546",
"agentSubmittedLatitude": "6.6053929",
"reportGeolocationUrl": null,
"mapAddressUrl": null,
"submissionDistanceInMeters": null,
"reasons": null,
"signature": null,
"images": [],
"buildingType": null,
"buildingColor": null,
"gatePresent": false,
"gateColor": null,
"availabilityConfirmedBy": null,
"closestLandmark": null,
"additionalInfo": null,
"reportAgentAccess": null,
"incidentReport": null,
"description": "",
"reportId": "0d501eec-5f4d-4e14-a05b-173ce0dbb31e",
"downloadUrl": "https://api.youverify.co/v1/reports/0d501eec-5f4d-4e12-a05b-173ce0dbb31e/download/pdf",
"apiVersion": "v2",
"mysqlId": 4621,
"businessId": "61d880f1e8e15aaf24558f27",
"businessType": "business",
"userId": "61d880f2e8e15aaf24558f9c",
"type": "guarantor",
"createdAt": "2018-06-06T13:28:26.000Z",
"lastModifiedAt": "2022-01-07T18:28:48.374Z",
"metadata": {},
"_createdAt": "2018-06-06T14:28:2626+01:00",
"_lastModifiedAt": "2022-01-07T19:28:4848+01:00",
"verificationId": "5b17c55a24328",
"id": "61d88619e8e15aaf24a76d0f",
"user": {
"firstName": "Famous",
"lastName": "Ehichioya",
"middleName": "",
"email": "[email protected]",
"mobile": "23490xxxxxxx",
"countryCode": "NGN",
"id": "61d880f2e8e15aaf24558f9c"
}
}
}
{
"event": "address.completed",
"apiVersion": "v2",
"data": {
"candidate": {
"candidateId": "61d8853be8e15aaf24a1759f",
"firstName": "Kayode",
"middleName": "",
"lastName": "Oge",
"photo": "https://cdn.youverify.co/1640838946220-r6fvnt3g0YDgxYikH9e1y.png",
"email": "[email protected]",
"mobile": "08068xxxxxx"
},
"business": {
"name": "Conserveria Africana Limited(GBFOODS)",
"registrationNumber": "510302",
"email": "[email protected]",
"mobile": "08026xxxxxxx"
},
"agent": {
"firstName": "Fred",
"middleName": null,
"lastName": "Momoh",
"signature": "data:image/jpg;base64,iVBORw0KGgoAAAANSUhEUgAAAVQAAAGjCAYAAABzBe0",
"photo": "https://api.youverify.co/uploads/agents/images/f3edc8af968af72ca19724c0ba8d91446a8a0220.jpg"
},
"address": {
"latlong": {
"lat": "6.54303",
"lon": "3.3931607"
},
"flatNumber": "",
"buildingName": "",
"buildingNumber": "5A",
"subStreet": "",
"street": "14 hughes avenue",
"landmark": "Bukka Hut",
"state": "lagos",
"city": "Lagos",
"country": "Nigeria",
"lga": null
},
"referenceId": "5db0385991396",
"parentId": null,
"status": "completed",
"taskStatus": "VERIFIED",
"subjectConsent": "true",
"startDate": "2019-10-23T00:00:00.000Z",
"endDate": "2019-10-23T00:00:00.000Z",
"submittedAt": "2019-10-23T14:45:01.000Z",
"executionDate": "2019-10-23T14:45:01.000Z",
"completedAt": "2019-10-23T14:45:01.000Z",
"acceptedAt": "2019-10-23T12:24:19.000Z",
"revalidationDate": "2020-01-23T00:00:00.000Z",
"notes": [
{
"createdAt": "2019-10-23 15:44:34",
"note": "Verified"
}
],
"isFlagged": false,
"agentSubmittedLongitude": "3.3929242",
"agentSubmittedLatitude": "6.5416855",
"reportGeolocationUrl": "https://www.google.com/maps/search/?api=1&query=6.5416855, 3.3929242",
"mapAddressUrl": "https://www.google.com/maps/search/?api=1&query=5a+Olu+Osunkeye+Crescent+Gbagada%2C+Lagos+%2C+Lagos%2C+Nigeria",
"submissionDistanceInMeters": 151,
"reasons": null,
"signature": "data:image/jpg;base64,iVBORw0KGgoAAAANSUhEUgAAAVQAAAGjCAYAAABzBe0UAAAc4Ul",
"images": [
{
"filePath": "https://youverify-api-bucket.nyc3.digitaloceanspaces.com/reports/files/images/resize/2019-10-23/1571838290509_91527.jpg",
"fileType": "image/jpeg",
"height": 300,
"width": 400
}
],
"buildingType": null,
"buildingColor": null,
"gatePresent": false,
"gateColor": null,
"availabilityConfirmedBy": null,
"closestLandmark": null,
"additionalInfo": null,
"reportAgentAccess": null,
"incidentReport": null,
"description": "",
"reportId": "reports_6e002d9a-3f07-4978-8ef4-99510f8d4fdd",
"downloadUrl": "https://api.youverify.co/v1/reports/reports_6e002d9a-3f07-4978-8ef1-99510f8d4fdd/download/pdf",
"apiVersion": "v2",
"mysqlId": 123771,
"businessId": "61d880efe8e15aaf245582eb",
"businessType": "business",
"userId": "61d880f2e8e15aaf245591f8",
"type": "business",
"createdAt": "2019-10-23T13:24:09.000Z",
"lastModifiedAt": "2022-02-24T00:58:41.722Z",
"metadata": {},
"_createdAt": "2019-10-23T14:24:099+01:00",
"_lastModifiedAt": "2022-02-24T01:58:4141+01:00",
"verificationId": "5db0385991396",
"id": "61d88618e8e15aaf24a7624b",
"user": {
"firstName": "Famous",
"lastName": "Ehichioya",
"middleName": "",
"email": "[email protected]",
"mobile": "2348036xxxxxx",
"countryCode": "NGN",
"id": "61d880f2e8e15aaf245591f8"
}
},
}
NB: Please note that the above symbol " | " is used to differentiate the possible outcomes.
Last modified 1yr ago