Webhooks
Webhooks
Webhooks CONTENTS
Contents
1 Intro 2
5 Sample notifications 5
5.1 Video.Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.2 Video.Consolidated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.3 Video.Failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4 Video.Verified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.1 Accepted Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.2 Rejected Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.5 Verification.Canceled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.5.1 Canceled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.6 Conversation.Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.7 Conversation.Updated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.8 Signature.Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.8.1 Successfull signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.8.2 Failed signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.9 Signature.CertificateRequest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.9.1 Requested . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.9.2 Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.9.3 Failed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1
Webhooks 2 CONFIGURING THE WEBHOOK
1 Intro
The eID API uses Webhooks to notify whenever certain events happens. Currently supported
events are:
You will need to configure a Webhook listener in your application (over HTTPS) that will receive
the notification of the event, along with its associated data. The listener must respond with a
200 HTTP code to consider the notification as successfully received. If a different HTTP code
is received, or if your listener fails to respond, another attempt to send the notification will be
repeated after 10 minutes, and this process will continue until a 200 HTTP code is received or the
5th attempt is reached.
2
Webhooks 3 RESENDING A WEBHOOK NOTIFICATION
2.1 Parameters
• Url: Endpoint (your endpoint) where you have configured your listener and the notification
will be sent. Only port 443 is allowed.
All events are configured in the same way, and you can use the same URL for more than one
event.
This will start the entire process again, in which, it will perform 5 attempts to deliver this notification.
3
Webhooks 4 VALIDATING THE WEBHOOK NOTIFICATION
4
Webhooks 5 SAMPLE NOTIFICATIONS
same notification will have an updated timestamp, and hence, an updated signature. If the body
or the timestamp are tampered with by a third party, the signature will be invalid. For the HMAC
key your Secret (which you can retrieve from your dashboard) is used. Below you’ll see the steps
required to verify the signature:
• A colon character:
• The body of the notification: The JSON payload converted to a String, with all the
spaces removed. This would result on a single line String like the following:
{"id":"8b6591af-ef64-4648-a265-df71cacdf559",
"date":1519641991208,
"tenantId":"3affddfc-2dfa-41b4-aed8-75e0e054cb48",
"event":"Video.Verified",
"data":{"id":"c0e041ca-e4f7-4ab8-851f-42d8420a28ec"}
2. Using your Secret as key, and the previous generated String as message, compute an
HMAC with SHA256 as hashing function
3. Compare the generated HMAC with the signature in the header x-eid-signature; if different,
the notification has been altered.
5 Sample notifications
5.1 Video.Completed
{
"id": {uuid},
"date": 1605272501303,
"tenantId": {uuid},
"event": "Video.Completed",
"data": {
"id": {uuid},
"process": "Unattended",
"status": "Completed",
"tenantId": {uuid},
"idType": 61,
"request": {
"minSimilarityLevel": "Low",
5
Webhooks 5 SAMPLE NOTIFICATIONS
"date": 1605272457000
},
"completion": {
"date": 1605272500000
},
"document": {
"passportNumber": "PAJ012345",
"scan": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"classification": "esp_p_2015",
"type": "TD3",
"issuer": "ESP",
"expiryDate": "290411",
"expiryDateTS": 1870560000000,
"subject": {
"photo": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"signature": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"primaryName": "MARIA",
"secondaryName": "LOPEZ PEREZ",
"birthDate": "870623",
"birthDateTS": 551404800000,
"sex": "F",
"nationality": "ESP",
"personalNumber": "A0012345678"
}
},
"biometrics": {
"face": {
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"similarityLevel": "High"
}
},
"features": {
"header2": {
"name": "Header 2",
"found": false,
"side": "Data"
},
"header1": {
"name": "Header 1",
"found": true,
"bbox": {
6
Webhooks 5 SAMPLE NOTIFICATIONS
"x": 21,
"y": 21,
"width": 145,
"height": 33
},
"side": "Data"
},
"signature": {
"name": "Signature",
"found": true,
"bbox": {
"x": 193,
"y": 251,
"width": 212,
"height": 66
},
"side": "Data"
},
"photo": {
"name": "Photo",
"found": true,
"bbox": {
"x": 32,
"y": 167,
"width": 141,
"height": 141
},
"side": "Data"
},
"ovi1": {
"name": "OVI",
"found": true,
"bbox": {
"x": 197,
"y": 13,
"width": 49,
"height": 33
},
"side": "Data"
}
},
7
Webhooks 5 SAMPLE NOTIFICATIONS
"securityChecks": {
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
},
"liveness": {
"name": "Liveness detection",
"passed": true
},
"notFaceSpoofing": {
"name": "Not face spoofing detected",
"passed": true
}
}
}
}
5.2 Video.Consolidated
{
"id": {uuid},
"date": 1690539079887,
"tenantId": {uuid},
"event": "Video.Consolidated",
"data": {
"videoFile": {
"id": {uuid},
"status": "Ready",
"size": 2657970,
"resolution": {
"width": 640,
"height": 480
},
8
Webhooks 5 SAMPLE NOTIFICATIONS
"duration": 42,
"fps": 25,
"format": {
"container": "mp4",
"codec": "h264"
},
"hash": "25f6e5542b4f26c710a89b5fd29697fb1217e3a2f36ee939956c9ea9fe85eaba"
},
"videoID": {
"id": {uuid},
"process": "Unattended",
"status": "Completed",
"tenantId": {uuid},
"idType": 62,
"request": {
"date": 1690370262000
},
"completion": {
"date": 1690370327000
},
"document": {
"type": "TD1",
"documentNumber": "BMH147038",
"front": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"back": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"classification": "esp_id_2015",
"issuer": "ESP",
"expiryDate": "270825",
"expiryDateTS": 1819152000000,
"nonExpiring": false,
"ocr": {
"front": {
"confidenceLevel": "High",
"confidence": 95.28694
},
"back": {
"confidenceLevel": "High",
"confidence": 98.4631
}
},
"subject": {
9
Webhooks 5 SAMPLE NOTIFICATIONS
"photo": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"signature": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"primaryName":"PEDRO",
"secondaryName":"PEREZ HERNANDEZ",
"birthDate":"951018",
"birthDateTS":813974400000,
"sex":"M",
"nationality":"ESP",
"personalNumber":"12345678Z"
}
},
"biometrics": {
"face": {
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/...",
"similarityLevel": "High"
}
},
"features": {
"clearWindow1": {
"name": "Clear Window",
"found": false,
"side": "front"
},
"clearWindow2": {
"name": "Clear Window",
"found": false,
"side": "back"
},
"header2": {
"name": "Header 2",
"found": true,
"bbox": {
"x": 261,
"y": 21,
"width": 225,
"height": 25
},
"side": "front"
},
"chip": {
"name": "Chip",
10
Webhooks 5 SAMPLE NOTIFICATIONS
"found": true,
"bbox": {
"x": 53,
"y": 125,
"width": 105,
"height": 97
},
"side": "back"
},
"header1": {
"name": "Header 1",
"found": false,
"side": "front"
},
"signature": {
"name": "Signature",
"found": true,
"bbox": {
"x": 252,
"y": 329,
"width": 154,
"height": 54
},
"side": "front"
},
"photo": {
"name": "Photo",
"found": true,
"bbox": {
"x": 68,
"y": 136,
"width": 125,
"height": 167
},
"side": "front"
},
"ovi1": {
"name": "OVI",
"found": true,
"bbox": {
"x": 197,
11
Webhooks 5 SAMPLE NOTIFICATIONS
"y": 13,
"width": 65,
"height": 41
},
"side": "front"
},
"badge1": {
"name": "Badge 1",
"found": true,
"bbox": {
"x": 277,
"y": 109,
"width": 209,
"height": 193
},
"side": "front"
}
},
"securityChecks": {
"nonExpired": {
"name": "Document not expired",
"passed": true
},
"notUnderage": {
"name": "Not underage",
"passed": true,
"attributes": {
"minAge": 18
}
},
"dataIntegrity": {
"name": "Data integrity",
"passed": true
},
"liveness": {
"name": "Liveness detection",
"passed": true
},
"notBWCopy": {
"name": "Not black & white copy",
"passed": true
12
Webhooks 5 SAMPLE NOTIFICATIONS
},
"sidesMatch": {
"name": "Document sides match",
"passed": true,
"attributes": {
"confidence": 78
}
},
"notFaceSpoofing": {
"name": "Not face spoofing detected",
"passed": true
}
},
"phases": {
"order": [
"Front",
"Back",
"Face"
]
},
"softwareVersions": [{
"name": "videoId.backend",
"version": "2.57.0"
},{
"name": "JavaScript.sdk",
"version": "3.38.1"
}
]
}
}
}
5.3 Video.Failed
{
"id": {uuid},
"date": 1605272299221,
"tenantId": {uuid},
"event": "Video.Failed",
"data": {
"id": {uuid},
13
Webhooks 5 SAMPLE NOTIFICATIONS
"process": "Unattended",
"status": "Failed",
"tenantId": {uuid},
"idType": 62,
"request": {
"minSimilarityLevel": "Low",
"date": 1605272245000
},
"failure": {
"id": {uuid},
"date": 1605272299000,
"reason": "Luminance.TooLow",
"category": "Environment.Error",
"data": {
"phase": "Front"
}
},
"biometrics": {},
"features": {},
"securityChecks": {}
}
}
5.4 Video.Verified
14
Webhooks 5 SAMPLE NOTIFICATIONS
"issuer": "ESP",
"nationality": "ESP",
"sex": "M",
"personalNumber": "12345678Z",
"documentNumber": "0AM1D1895",
"birthDate": 299893300000,
"expiryDate": 1503324800000
}
}
}
5.5 Verification.Canceled
5.5.1 Canceled
{
"id": "e5da2d82-853e-4fcf-84ce-d74a75b4e297",
"date": 1676379097946,
15
Webhooks 5 SAMPLE NOTIFICATIONS
"tenantId": "c1db775d-7b4d-4e48-be64-f2ba73ee3f40",
"appId": "c1db775d-7b4d-4e48-be64-f2ba73ee3f40",
"webhook": {
"_id": "028669ae-8db4-4f50-b7a3-565bb14c15c7"
},
"event": "VerificationCanceled",
"data": {
"id": "6c44df85-db0b-4645-a06b-b2d8ae43a528",
"version": "v3",
"type": "eu.electronicid.verifications.contract.verification_requests.events.
VerificationRequestCanceledEidEvent",
"date": 1676379097926,
"source": "verifications.api",
"tenantId": "c1db775d-7b4d-4e48-be64-f2ba73ee3f40",
"data": {
"id": "88f036c8-0738-4d7e-af26-557d17aa939c",
"tenantId": "c1db775d-7b4d-4e48-be64-f2ba73ee3f40",
"rauthorityId": "d4c4b7bd-2d7e-48c3-9764-f9a4744c0702",
"externalReference": "Prueba_QA",
"fullName": "JUAN GARCIA GARCIA",
"videoId": "ee411578-bd4f-49c4-9312-631796e20609",
"priority": {
"value": "medium",
"expiration": 7200000
},
"status": "Canceled",
"createdDate": 1676379097886,
"dueDate": 1676386297886,
"lastModifiedDate": 1676379097926,
"assignments": 0,
"reasonForCancellation": "CONSOLIDATION_FAILED"
}
}
}
5.6 Conversation.Completed
{
"id": "6390a578-8168-4ccb-8203-59e38f43cb2a",
"event": "Conversation.Completed",
"tenant": "...",
16
Webhooks 5 SAMPLE NOTIFICATIONS
"date": 1624276599899,
"ip": "10.30.100.100",
"conversationId": "55228939-3a9c-4f70-a213-5234a7a799bf",
"conversation": {
"id": "55228939-3a9c-4f70-a213-5234a7a799bf",
"workflow": {
"id": "...",
"name": "..."
},
"tenant": "...",
"status": "Completed",
"creationDate": 1624276501471,
"completionDate": 1624276599899,
"inputs": {
},
"outputs": {
}
}
}
5.7 Conversation.Updated
{
"id": "09bb4ce9-79b5-4456-b453-3054ad152d06",
"event": "Conversation.Updated",
"tenant": "...",
"date": 1623749340366,
"ip": "NOT_FOUND",
"conversationId": "e6e6645d-166f-4905-8dec-dc82208892f3",
"componentName": "finishButton",
"step": "OpenUrlCompleted",
"data": {
"url": "https://www.electronicid.eu/"
},
"conversation": {
"id": "e6e6645d-166f-4905-8dec-dc82208892f3",
"workflow": {
"id": "...",
"name": "..."
},
"tenant": "...",
17
Webhooks 5 SAMPLE NOTIFICATIONS
"status": "Ongoing",
"creationDate": 1623749330246,
"inputs": {
},
"outputs": {
}
}
}
5.8 Signature.Completed
18
Webhooks 5 SAMPLE NOTIFICATIONS
},
"rauthority": {
"name": "Company"
}
},
"signDate": 1625221669836,
"status": "Completed",
"externalReference": "externalID",
"documents": [
{
"signatureId": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"originalDocument": {
"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000
},
"signedDocument": {
"documentId": "f866ef11-3147-4696-b692-afb6b3063d49",
"name": " document.pdf",
"creationDate": 1499099452263
}
}
]
}
}
}
19
Webhooks 5 SAMPLE NOTIFICATIONS
"date": 1625221602940,
"error": 1088,
"message": "Identification is not valid for signature."
}
}
}
5.9 Signature.CertificateRequest
5.9.1 Requested
{
"id": "b3588ed7-a7ba-4aed-8672-147572a7f619",
"date": 1676986667107,
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"event": "Signature.CertificateRequest",
"data": {
"version": "v2",
"id": "a83cad8d-d023-4486-a640-5e89c2d698b7",
"type": "eu.electronicid.events.certificate.CertificateRequestEidEvent",
"date": 1676986667078,
"source": "signatureid.api",
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"externalReference": "prueba",
"legacy": {
"entityId": "db1651ea-1b22-4c1a-b809-588dfb151786",
"personalNumber": "12345678Z"
},
"data": {
"certificateRequest": {
"certificateRequestId": "db1651ea-1b22-4c1a-b809-588dfb151786",
"status": "REQUESTED",
"identification": {
"id": "09b8166a-c6e2-44ea-899a-cdf320097e71",
"type": "video",
"status": "VALID",
"identity": {
"id": "d52401a9-8f3b-401b-af72-b4ec9de2f5d3",
"nif": "12345678Z",
"personalInfoId": "f923e1f2-ac2d-4bb1-b15d-548450cb0951",
"primaryName": "JUAN",
"secondaryName": "GARCIA GARCIA",
20
Webhooks 5 SAMPLE NOTIFICATIONS
"phone": "666123456",
"email": "[email protected]"
}
},
"externalReference": "prueba"
}
}
}
}
5.9.2 Completed
{
"id": "ddd3a314-06e8-4b50-be86-6d5123644a50",
"date": 1676986856815,
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"event": "Signature.CertificateRequest",
"data": {
"version": "v2",
"id": "df04ca22-8135-4dae-9ca4-8d7705e58aca",
"type": "eu.electronicid.events.certificate.CertificateRequestEidEvent",
"date": 1676986856761,
"source": "signatureid.api",
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"externalReference": "prueba",
"legacy": {
"entityId": "db1651ea-1b22-4c1a-b809-588dfb151786",
"personalNumber": "12345678Z"
},
"data": {
"certificateRequest": {
"certificateRequestId": "db1651ea-1b22-4c1a-b809-588dfb151786",
"status": "COMPLETED",
"identification": {
"id": "09b8166a-c6e2-44ea-899a-cdf320097e71",
"type": "video",
"status": "VALID",
"identity": {
"id": "d52401a9-8f3b-401b-af72-b4ec9de2f5d3",
"nif": "12345678Z",
"personalInfoId": "f923e1f2-ac2d-4bb1-b15d-548450cb0951",
21
Webhooks 5 SAMPLE NOTIFICATIONS
"primaryName": "JUAN",
"secondaryName": "GARCIA GARCIA",
"phone": "666123456",
"email": "[email protected]"
}
},
"externalReference": "prueba"
}
}
}
}
5.9.3 Failed
{
"id": "124de84a-e1af-4cf3-9b77-c3da5abac8ee",
"date": 1676984312481,
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"event": "Signature.CertificateRequest",
"data": {
"version": "v2",
"id": "9667d846-c817-447c-80f3-57b720c9a75a",
"type": "eu.electronicid.events.certificate.CertificateRequestEidEvent",
"date": 1676984312355,
"source": "signatureid.api",
"tenantId": "f3be3092-b681-4b4e-a0d3-65806718ec2b",
"externalReference": "prueba",
"legacy": {
"entityId": "5849cae8-7508-4f8b-9a18-d371be34f0a0",
"personalNumber": "12345678Z"
},
"data": {
"certificateRequest": {
"certificateRequestId": "5849cae8-7508-4f8b-9a18-d371be34f0a0",
"status": "FAILED",
"identification": {
"id": "09b8166a-c6e2-44ea-899a-cdf320097e71",
"type": "video",
"status": "VALID",
"identity": {
"id": "d52401a9-8f3b-401b-af72-b4ec9de2f5d3",
"nif": "12345678Z",
22
Webhooks 5 SAMPLE NOTIFICATIONS
"personalInfoId": "f923e1f2-ac2d-4bb1-b15d-548450cb0951",
"primaryName": "JUAN",
"secondaryName": "GARCIA GARCIA",
"phone": "666123456",
"email": "[email protected]"
}
},
"externalReference": "prueba"
}
}
}
}
23