Webhooks
Webhooks keep your system in sync with the status of the bronID verifications. You will receive a webhook every time there is a change in the verification status of your KYC entries. This includes an initial webhook when you submit the KYC. The initial webhook will have the same value as the HTTP response you get from the API. For security reasons, always verify the signature of the webhook to confirm it came from bronID.
Webhooks get triggered when:
- There is a new KYC submission (through the API or the bronID Portal)
- There is a change in the status of the verification
The verification status of the webhooks can be:
- pending - the verification is pending processing
- verified - the verification was successful
- rejected - the verification was not successful
- info - (legal entities only) additional information required for verification
- locked - too many unsuccessful verification attempts
Look up the understanding results documentation for more details.
Webhook response parameters
Name | Type | Description |
---|---|---|
name | string | The full name of the entity / individual |
verificationStatus | string | The verification status - verified / rejected / pending / info / locked (see details) |
verificationUuid | string | (deprecated - use trace and submissionId) The UUID of the verification |
trace | string | Entities: The UUID of the verification, Individuals: The UUID of the specific verification attempt |
submissionId | string | Entities: same as trace, Individuals: The UUID of the verification grouping |
parentVerificationTrace | string | Entities: not present, Individuals: The verificationUuid of the encapsulating entity - Only exists if verified as part of an entity |
parentVerificationUuid | string | SAME AS "parentVerificationTrace" |
parentUserId | string | Entities: not present, Individuals: The userId of the encapsulating entity - Only exists if verified as part of an entity |
entityType | string | The entity type of the verification (Note: customer might change this when using Whitelabel forms) |
timestamp | number | Timestamp when the webhook was sent |
userId | string | The userId connected to this verification (if supplied) |
submissionStatus | string | Helper status - whether the data has been received by bronID - submitted / incomplete / locked |
verificationScore | number | Entities: not present, Individuals: Indication of the number of data sources matched |
stakeholders | array | An array of stakeholders connected to this verification |
screeningId | string | The identifier of the performed PEPs & Sanctions screening - if configured |
idvRiskScore | object | The ID Verification risk of the entity/individual (Undefined / Low / Low to Medium / Medium / Medium to High / High) |
stakeholders | object array | The details of verified stakeholders part of the verification |
requestedActions | array | Individuals or documents that need to supplied to continue the verification process (see details) |
signature | object | Used to verify the webhook source is bronID |
Webhook examples
We will look at some webhooks results to show you their structure and how to handle them.
Pending webhook
The pending webhook means that the KYC verification is pending processing. The status of this verification will change into verified, rejected or info.
Here is the example of the pending webhook:
{
"name": "My Company",
"verificationStatus": "pending",
"entityType": "privateCompany",
"verificationUuid": "63152524-c722-4a44-8931-1c6caad4dbcf",
"timestamp": 1585549407,
"userId": "yourUniqueUserId",
"submissionStatus": "submitted",
"stakeholders": [],
"idvRiskScore": {
"description": "Medium",
},
"signature": {
"version": "1",
"sha256": "bronid_sec_sha256_340cb830d92ecebbc88709d4828c39a33884004bd92fc55523c7e36ba3d07728",
"keccak256": "bronid_sec_keccak256_080b5c54352977d8bbdbffe7f9cc90fa08fcaf53e6814b50728fc79e3d9f75d2"
}
}
Verified webhook
The verified webhook means that the KYC verification has satisfied the bronID verification requirements.
Here is the example of the verified webhook:
{
name: "My Unregulated Trust",
verificationStatus: "verified",
entityType: "unRegulatedTrust",
verificationUuid: "63152524-c722-4a44-8931-1c6caad4dbcf",
trace: "63152524-c722-4a44-8931-1c6caad4dbcf",
submissionId: "63152524-c722-4a44-8931-1c6caad4dbcf",
timestamp: 1585548662,
userId: "yourUniqueUserId",
submissionStatus: "submitted",
idvRiskScore: {
description: "Low",
},
stakeholders: [
{
id: "14c4d03d-b484-468a-bf32-822be11b84fc",
submissionId: "37fcaaf6-c409-48f5-950f-9ec987bbf44d",
trace: "63152524-c722-4a44-8931-1c6caad4dbcf",
verificationUuid: "63152524-c722-4a44-8931-1c6caad4dbcf",
name: "First ok Last",
role: "beneficiaries",
submissionStatus: "submitted",
timestamp: 1701656768,
verificationScore: 200,
verificationStatus: "verified",
idvRiskScore: {
description: "Low"
},
outOfWatchLists: [{
"Country Name": "The country of the watchlist",
name: "The name of the watchlist",
description: "The description of the watchlist",
link: "https://the.link.com"
}],
inWatchLists: [{
"Country Name": "International",
description: "The PEP list is a pro...",
link: "https://bronid.com",
name: "PEP List",
results: [
// the results of the PEP list - https://docs.bronid.com/peps-and-sanctions
]
}],
},
{
id: "017cce93-399d-425a-8fc9-29315979e1da",
idvRiskScore: {
description: "Undefined"
},
name: "My Comp Pty Ltd",
role: "trustee",
submissionStatus: "submitted",
verificationStatus: "pending",
}
],
signature: {
version: "1",
sha256: "bronid_sec_sha256_d1a08cf016dcb86c4a4d551220eba5da6ba51e12bbb1c78d7bab01e9cea87885",
keccak256: "bronid_sec_keccak256_20d89ffa5870fbb2cc577585e431f626a586857b164d34a902bfd17bc61be75e"
}
}
Rejected webhook
The rejected webhook means that the KYC verification has not has satisfied the bronID verification requirements.
Here is the example of the rejected webhook:
{
"name": "My Company",
"verificationStatus": "rejected",
"entityType": "privateCompany",
"verificationUuid": "63152524-c722-4a44-8931-1c6caad4dbcf",
"timestamp": 1585548940,
"userId": "yourUniqueUserId",
"submissionStatus": "submitted",
"stakeholders": [],
"idvRiskScore": {
"description": "Medium",
},
"signature": {
"version": "1",
"sha256": "bronid_sec_sha256_d4dab7958f6205adc6e52f3d3a3947c6a7677b7b4aca84780c8770013bec0786",
"keccak256": "bronid_sec_keccak256_7dd112ee1255367ff5cc17a3199b162ac9307d781dbbc407264cc95202838242"
}
}
Info webhook
The info webhook means that you need to provide more details to complete the verification. In this example we will look at a verification that is missing a stakeholder (individual) and a document.
Here is the example of the info webhook:
{
"verificationStatus": "info",
"entityType": "privateCompany",
"name": "THE ENTITY NAME",
/* the verificationUuid which has missing information */
"verificationUuid": "63152524-c722-4a44-8931-1c6caad4dbcf",
"trace": "63152524-c722-4a44-8931-1c6caad4dbcf",
"timestamp": 1583455152245,
"userId": "theSubmittedUserId",
"idvRiskScore": {
"description": "Medium",
},
/* these are the requestedActions */
"requestedActions": [
{
"type": "individual",
"role": "trustee",
/* the missing stakeholder id */
"id": "5ad6b33c-44f1-4b12-9ec9-31fadd41f6c3",
"fields": {
/* information about the missing stakeholder */
"country": "AUS",
"firstName": "Jane",
"lastName": "Citizen",
"middleName": ""
}
},
{
"type": "document",
/* the missing document id */
"id": "a2820913-8be8-4cd9-bacc-29b6cfd2d38c",
/* the name of the requested document */
"extractType": "Trust Deed for My Entity"
}
]
}
You can submit the information for the requestedActions with a follow-up request:
{ "metadata_version": "4", "metadata_serviceUid": "yourServiceUid", "metadata_secretKey": "yourSecretKey", /* this matches the verificationUuid of the info verification */ "verificationUuid": "cd0c518f-7084-49ff-802a-9c517245daf2", /* these are the requestedActions */ "requestedActions": [ { "type": "individual", "role": "trustee", /* this matches the id of the requested stakeholder */ "id": "5ad6b33c-44f1-4b12-9ec9-31fadd41f6c3", "fields": { "country": "AUS", "firstName": "Jane", "lastName": "Citizen", "middleName": "", "gender": "female", "dateOfBirth": "20/10/1982", "unitNumber": "1", "streetNumber": "94", "streetName": "lennox", "streetType": "Street", "suburb": "CASINO", "postcode": "2470", "state": "NSW", "email": "email@domain.com" } }, { "type": "document", /* this matches the id of the requested document */ "id": "a2820913-8be8-4cd9-bacc-29b6cfd2d38c", /* the base64 of the document */ "documentBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", } ] }
Locked webhook
The locked webhook means that the KYC verification has not has satisfied the bronID verification requirements.
Here is the example of the locked webhook:
{
"name": "My Company",
"verificationStatus": "locked",
"entityType": "privateCompany",
"verificationUuid": "63152524-c722-4a44-8931-1c6caad4dbcf",
"timestamp": 1585548940,
"userId": "yourUniqueUserId",
"submissionStatus": "submitted",
"stakeholders": [],
"signature": {
"version": "1",
"sha256": "bronid_sec_sha256_d4dab7958f6205adc6e52f3d3a3947c6a7677b7b4aca84780c8770013bec0786",
"keccak256": "bronid_sec_keccak256_7dd112ee1255367ff5cc17a3199b162ac9307d781dbbc407264cc95202838242"
}
}
Verify webhook source
You can verify the webhook came from bronID by re-creating the signature on your side. To create the signature, append the pre-shared signing key to the end of the payload and then generate a hash. Your hash should match the webhook signature.
The response contains two signatures - KECCAK256 and SHA3-256.
Note: SHA3-256 gives different results than SHA-256 (part of the SHA2 family).
Note: Omit the signatures from the response when signing the payload in your code.
Here is an example of a signed response:
{
/* payload start */
"name": "My Company",
"verificationStatus": "verified",
"verificationUuid": "63152524-c722-4a44-8931-1c6caad4dbcf",
"timestamp": 1585548940,
"userId": "yourUniqueUserId",
"submissionStatus": "submitted",
"stakeholders": [],
/* payload end */
/* omit the signature to verify source */
"signature": {
"version": "1",
"sha256": "bronid_sec_sha256_d4dab7958f6205adc6e52f3d3a3947c6a7677b7b4aca84780c8770013bec0786",
"keccak256": "bronid_sec_keccak256_7dd112ee1255367ff5cc17a3199b162ac9307d781dbbc407264cc95202838242"
}
}