Content Comparison

Table of Contents

Table of Contents

minLevel	1
maxLevel	7

ℹ️ About webhooks

Webhooks enable Ondato to send real-time notifications about changes in your resources. These notifications are sent as POST requests to your server immediately after the event occurs, and the request body includes information about the resource.

🔐 Security

Ondato uses HTTPS to transmit these notifications in the form of a JSON payload.

🛒 Ordering

Ondato delivers events asynchronously. Therefore, you might receive them out of order and need to handle them accordingly.

📫 Webhook IP addresses

All webhook requests will originate from the following IP addresses:

Code Block
20.31.10.47 20.31.227.231 20.76.229.117 20.76.229.248 213.226.187.101

Please ensure that you whitelist the above IPs to receive webhook notifications.

🔃 Retry logic

Upon sending a webhook notification, we are waiting for a success response for 30 seconds. Otherwise, if your endpoint does not respond, the webhook is queued for retry.

We use an exponential backoff retry policy for event delivery. The attempt to resend the notifications is according to the following schedule on a best effort basis:

Panel

panelIconId	23f1
panelIcon	:stopwatch:
panelIconText	⏱️
bgColor	#F4F5F7

10 seconds
30 seconds
1 minute
5 minutes
10 minutes
30 minutes
1 hour
3 hours
6 hours
Every 12 hours up to 24 hours

If the endpoint responds within 3 minutes, we will make an attempt to remove the event from the retry queue on a best-effort basis. However, duplicates may still be received.

A small degree of randomization is incorporated into all retry steps and may selectively skip certain retries if an endpoint is offline for an extended period or seems to be overloaded.

The maximum number of retry attempts is 30.

When Event Grid is unable to deliver an event within a specific time period frame or after attempting to deliver the event a certain number of times, the event is dropped.

❔ How to start receiving webhooks?

To begin receiving event notifications in your application, you need to follow these steps:

Identify the events you want to monitor.
📄 Please see a full list of events in this section here: https://ondato.atlassian.net/wiki/spaces/PUB/pages/2296184995/Webhooks#%F0%9F%AA%84-Webhook-types.
Create a webhook endpoint as an HTTP endpoint on your local server.
Handle requests from Ondato.
Deploy your webhook endpoint to make it publicly accessible via an HTTPS URL.
Contact the Ondato support team to register the publicly accessible HTTPS URL and provide a list of events you would like to monitor.

Please note that we also support multiple URLs for sending webhooks.

😶‍🌫️ Requirements for webhook endpoint

Ondato needs to know where to send information about events. To receive webhooks, you must create a webhook endpoint and provide us with the a publicly accessible HTTPS URL that meets the following criteria:

URL format: https://<your-website-name>/<your-webhook-endpoint>
URL must support
Status
colour Green
title POST
HTTP method.
URL must be secure (HTTPS protocol).
URL must support one of the available authentication flows:
1. basic | username, password
2. oAuth2 | clientID, clientSecret, tokenUrl
3. HMAC | client-side verification

Handling webhooks events with HMAC Authentication

Info
To start receiving webhooks events with HMAC authentication you should first receive your secret from Ondato.

HMAC webhook verification steps:

1. In web request you would receive the Ondato-Signature header
Request header example:
Ondato-Signature: t=1712825621, s=7026783cfd8b88a2652f23e789f1ec7de02b7c6ef8362892fe743fead4bab71d

2. Parse value t from the header (for given example 1712825621) - timestamp

3. Get received body/json string - json

4. Join to a single string $"{timestamp}.{json}" (joining to single string may vary on your programming environment) - message

5. Using secret compute HMACSHA256 hash (lower case) for message - computedHash

6. Parse value s from the header (for a given example 7026783cfd8b88a2652f23e789f1ec7de02b7c6ef8362892fe743fead4bab71d) - signature

7. Compare computedHash with signature - those should match

Panel

panelIconId	1f3af
panelIcon	:dart:
panelIconText	🎯
bgColor	#F4F5F7

Events sent by Ondato will have a body in the following structure:

Property

Description

Id

Webhook ID

ApplicationId

Internal ID to identify you in the Ondato system.

CreatedUtc

Date and time when the webhook was generated.

DeliveredUtc

Date and time when the webhook was delivered.

Panel

panelIconId	atlassian-info
panelIcon	:info:
bgColor	#F4F5F7

This property is only visible via Webhooks API. and is not sent with the body of the Webhook itself.

IsDelivered

Status of the webhook if it was delivered or not. Possible values are true/ false.

Panel

panelIconId	atlassian-info
panelIcon	:info:
bgColor	#F4F5F7

This property is only visible via Webhooks API. and is not sent with the body of the Webhook itself.

Payload

Depending on the webhook type property, the payload always returns the same information you could obtain from the

Status

colour	Blue
title	get

endpoint of the resource.

For example, the webhook type is KycIdentification.<event>, and then the payload will contain information that you can retrieve from the KYC ID endpoint

Status

colour	Blue
title	get

/identifications/{id}.

Information about each event payload is here.

Type

Type of the webhook. It consists of two parts (the first part identifies the service and the second one, the event):

🪄 Webhook types

Info
You have the option to configure various webhook types that can trigger a message to registered webhooks.

🆔 Identity Verification (IDV) webhooks

1️⃣ `IdentityVerification.StatusChanged`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the identity verification (IDV) status changes.

For this webhook type, the payload body depends on the IDV API →
Status
colour Blue
title get
/v1/identity-verifications/{id} contract.
You can call IDV API by using "id" →
Status
colour Blue
title get
/v1/identity-verifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "03be8be3-fbd5-4496-b552-bcd3e4918116"
        }
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "7a21b0e2-580e-4d2d-8578-00fc32a753ad",
    "applicationId": "44575362-e08e-4f75-b399-00d9d8916552",
    "createdUtc": "2023-01-31T07:25:55.6073016Z",
    "payload": {
        "id": "03be8be3-fbd5-4496-b552-bcd3e4918116",
        "status": "Completed",
        "applicationId": "44575362-e08e-4f75-b399-00d9d8916552",
        "createdUtc": "2023-01-31T07:22:11.313Z",
        "modifiedUtc": "2023-01-31T07:25:55.595Z",
        "setup": {
            "id": "5f16990b-d00a-4ff2-8102-e7b8d5820c28",
            "versionId": "60e8a778-1885-4162-bd58-d8b07bddba2e"
        },
        "step": {
            "kycIdentification": {
                "id": "6df0d302-f0bb-441a-804c-5b114b476fc0"
            },
            "documentSignatures": [],
            "forms": [],
            "consent": {
                "isConsented": true,
                "consentedUtc": "2023-01-31T07:22:25.08Z"
            }
        }
    },
    "type": "IdentityVerification.StatusChanged"
}

2️⃣ `IdentityVerification.Consented`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the consent step has been processed.

For this webhook type, the payload body depends on the IDV API →
Status
colour Blue
title get
/v1/identity-verifications/{id} contract.
In the webhook payload, you receive the "id" as a reference to the Consents API.
You can call Consents API by using “id” →
Status
colour Blue
title get
/v1/consents/{id} to retrieve the information about the consent session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "6c14b207-f73f-4a85-9e38-bbfb5ca62858"
        "step": {
            "consent": {
            }
        }
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "e4df532d-a448-43b2-a875-031475695cf2",
    "applicationId": "a2af2fd1-60aa-4549-ab2e-e6294385af62",
    "createdUtc": "2023-02-21T07:47:06.196653Z",
    "payload": {
        "id": "6c14b207-f73f-4a85-9e38-bbfb5ca62858",
        "status": "InProgress",
        "applicationId": "a2af2fd1-60aa-4549-ab2e-e6294385af62",
        "createdUtc": "2023-02-21T07:46:57.862Z",
        "modifiedUtc": "2023-02-21T07:47:06.14Z",
        "setup": {
            "id": "27820208-e4d0-4841-bacf-93e6e709637b",
            "versionId": "7cd83758-bc5f-4aa0-97cc-d7f3fa177dca"
        },
        "step": {
            "documentSignatures": [],
            "forms": [],
            "consent": {
                "isConsented": true,
                "consentedUtc": "2023-02-21T07:47:06.14Z"
            }
        }
    },
    "type": "IdentityVerification.Consented"
}

Note

Following fields can be ignored (are depreciated):

"isConsented"
"consentedUtc"

👤 KYC Identification webhooks

1️⃣ `KycIdentification.Created`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the KYC identification step is initiated by the customer.

For this webhook type, the payload body depends on the KYC ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYC ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "7175fc81-8ac1-418a-b2e4-89d0e8894442"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "e4e148de-8fd1-4e64-9173-00374ed139d2",
    "applicationId": "8c7218bd-9394-4603-b8ba-1ccea0b5e8d7",
    "createdUtc": "2023-01-10T12:16:53.4746293Z",
    "payload": {
        "id": "7175fc81-8ac1-418a-b2e4-89d0e8894442",
        "applicationId": "8c7218bd-9394-4603-b8ba-1ccea0b5e8d7",
        "createdUtc": "2023-01-10T12:16:53.319Z",
        "setup": {
            "id": "12d8478b-0174-49e9-b3e6-45f9063ba0d2",
            "versionId": "03a5ec17-18af-4e88-8a35-1f8ebdec2d3a"
        },
        "identityVerificationId": "ef9379b3-652d-44ee-b4c9-8da7a682ce40",
        "status": "Awaiting",
        "statusReason": "Unfinished",
        "isCrossChecked": false
    },
    "type": "KycIdentification.Created"
}

2️⃣ `KycIdentification.Processed`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the KYC identification is completed by the customer.

For this webhook type, the payload body depends on the KYC ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYC ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "c9fc134b-0386-4e4f-940e-f1349b9d3d64"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "25aa5e86-dd51-4a23-870d-0015e7d98227",
    "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
    "createdUtc": "2023-02-20T13:24:32.4234105Z",
    "payload": {
        "id": "c9fc134b-0386-4e4f-940e-f1349b9d3d64",
        "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
        "createdUtc": "2023-02-20T13:24:23.938Z",
        "setup": {
            "id": "d4915b8c-f4a7-4e94-a2c3-16c68a1aee78",
            "versionId": "f3135842-d53c-4525-8118-be63a12641ba"
        },
        "identityVerificationId": "7b4032ff-3a4a-4846-abf3-b1ffa9afbe26",
        "status": "Awaiting",
        "statusReason": "Processing",
        "isCrossChecked": false,
        "document": {
            "type": "IdCard",
            "mrzVerified": false,
            "files": [
                {
                    "createdUtc": "2023-02-20T13:24:26Z",
                    "fileId": "1d712a49-bcb4-47eb-ba33-0652dcebad2f",
                    "fileName": "c9fc134b03864e4f940ef1349b9d3d64_front_132425267.jpeg",
                    "fileExtension": "jpeg",
                    "part": "Front",
                    "fileType": "DocumentPhoto"
                }
            ],
            "ocrValidations": [
                {
                    "key": "Address",
                    "isValid": false
                },
                {
                    "key": "Category",
                    "isValid": true
                },
                {
                    "key": "DateOfBirth",
                    "isValid": false
                },
                {
                    "key": "DateOfExpiration",
                    "isValid": false
                },
                {
                    "key": "DateOfIssue",
                    "isValid": false
                },
                {
                    "key": "DocumentNumber",
                    "isValid": false
                },
                {
                    "key": "FirstName",
                    "isValid": false
                },
                {
                    "key": "LastName",
                    "isValid": false
                },
                {
                    "key": "Gender",
                    "isValid": false
                },
                {
                    "key": "Nationality",
                    "isValid": false
                },
                {
                    "key": "PersonalCode",
                    "isValid": false
                }
            ]
        },
        "rules": [
            {
                "name": "DocumentNotExpired",
                "status": "Fail",
                "reason": "DocumentExpirationDateNotFound"
            },
            {
                "name": "DocumentHasFace",
                "status": "Fail",
                "reason": "DocumentHasNoFace"
            },
            {
                "name": "DocumentHasBothSides",
                "status": "Fail",
                "reason": "DocumentPartTypeNotRecognized"
            },
            {
                "name": "DocumentTypeNotProhibited",
                "status": "Success"
            },
            {
                "name": "NotUnder18",
                "status": "Fail",
                "reason": "BirthDateNotFound"
            },
            {
                "name": "NotProhibitedByCountryOrState",
                "status": "Fail",
                "reason": "DocumentCountryOrStateUnknown"
            }
        ],
        "registries": [],
        "fraudChecks": [],
        "completedUtc": "2023-02-20T13:24:32Z"
    },
    "type": "KycIdentification.Processed"
}

3️⃣ `KycIdentification.Approved`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the KYC identification is manually or automatically approved.

For this webhook type, the payload body depends on the KYC ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYC ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "4c0000ac-f116-4dec-93ba-493f3809ca9b"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "00b6c3c8-8219-4206-a4ab-04554c97fa1a",
    "applicationId": "00cabb1f-4d7c-41d9-9a97-55482d920160",
    "createdUtc": "2023-01-16T23:40:52.4886646Z",
    "payload": {
        "id": "4c0000ac-f116-4dec-93ba-493f3809ca9b",
        "applicationId": "00cabb1f-4d7c-41d9-9a97-55482d920160",
        "createdUtc": "2023-01-16T23:40:42.77Z",
        "setup": {
            "id": "04b803f3-6c62-4560-bf5f-9ef75397ce1d",
            "versionId": "fde54820-00ec-4da0-87fa-c70f81729b0e"
        },
        "identityVerificationId": "d1a76177-00d5-494e-bbba-557527501a0e",
        "status": "Approved",
        "statusReason": "AutomaticallyIdentified",
        "isCrossChecked": false,
        "document": {
            "fullName": "NAME MIDDLE SURNAME",
            "firstName": "NAME MIDDLE",
            "lastName": "SURNAME",
            "documentNumber": "1740931767",
            "dateOfIssue": "2018-12-03",
            "dateOfExpiration": "2023-12-01",
            "dateOfBirth": "1985-02-27",
            "personalCode": "000.000.000-17",
            "countryIso3": "BRA",
            "type": "DriverLicense",
            "mrzVerified": true,
            "category": "B",
            "files": [
                {
                    "createdUtc": "2023-01-16T23:40:43Z",
                    "fileId": "e2ec5e00-0000-40f3-9e1c-c7a435d1fe2f",
                    "fileName": "4c4811acf1164dec93ba493f3809ca9b_front_234040000.jpeg",
                    "fileExtension": "jpeg",
                    "part": "Front",
                    "fileType": "DocumentPhoto"
                },
                {
                    "createdUtc": "2023-01-16T23:40:43Z",
                    "fileId": "717e98b1-00a-0000-ab51-655b8cf0bb2d",
                    "fileName": "4c4811acf1164dec93ba493f3809ca9b_back_234043541.jpeg",
                    "fileExtension": "jpeg",
                    "part": "Back",
                    "fileType": "DocumentPhoto"
                }
            ],
            "ocrValidations": [
                {
                    "key": "Address",
                    "isValid": true
                },
                {
                    "key": "Category",
                    "isValid": true
                },
                {
                    "key": "DateOfBirth",
                    "isValid": true
                },
                {
                    "key": "DateOfExpiration",
                    "isValid": true
                },
                {
                    "key": "DateOfIssue",
                    "isValid": true
                },
                {
                    "key": "DocumentNumber",
                    "isValid": true
                },
                {
                    "key": "FirstName",
                    "isValid": true
                },
                {
                    "key": "LastName",
                    "isValid": true
                },
                {
                    "key": "Gender",
                    "isValid": true
                },
                {
                    "key": "Nationality",
                    "isValid": true
                },
                {
                    "key": "PersonalCode",
                    "isValid": true
                }
            ]
        },
        "rules": [
            {
                "name": "DocumentHasBothSides",
                "status": "Success"
            },
            {
                "name": "DocumentNotExpired",
                "status": "Success"
            },
            {
                "name": "DocumentHasFace",
                "status": "Success"
            },
            {
                "name": "DocumentTypeNotProhibited",
                "status": "Success"
            },
            {
                "name": "NotUnder18",
                "status": "Success"
            }
        ],
        "registries": [],
        "fraudChecks": [
            {
                "name": "DocumentManipulation",
                "status": "Success"
            }
        ],
        "completedUtc": "2023-01-16T23:40:51Z"
    },
    "type": "KycIdentification.Approved"
}

4️⃣ `KycIdentification.Updated`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the document data of KYC Identification is updated in the Ondato Portal.

For this webhook type, the payload body depends on the KYC ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYC ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "9655ae23-7be6-4df4-98e4-df43a58f9620"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "a59c2055-7655-43bb-923d-0005928301d7",
    "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
    "createdUtc": "2023-02-16T14:46:33.1467591Z",
    "payload": {
        "id": "9655ae23-7be6-4df4-98e4-df43a58f9620",
        "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
        "createdUtc": "2023-02-16T14:43:40.503Z",
        "setup": {
            "id": "d4915b8c-f4a7-4e94-a2c3-16c68a1aee78",
            "versionId": "f3135842-d53c-4525-8118-be63a12641ba"
        },
        "identityVerificationId": "67c8dad4-b8ea-40aa-bced-7cdfb1e3199f",
        "status": "Rejected",
        "statusReason": "UnrelatedPhotoSubmit",
        "isCrossChecked": true,
        "document": {
            "type": "DriverLicense",
            "mrzVerified": true,
            "files": [
                {
                    "createdUtc": "2023-02-16T14:43:42Z",
                    "fileId": "25afc22e-9f87-4466-afb4-e1609141798a",
                    "fileName": "9655ae237be64df498e4df43a58f9620_front_144342156.png",
                    "fileExtension": "png",
                    "part": "Front",
                    "fileType": "DocumentPhoto"
                }
            ],
            "ocrValidations": [
                {
                    "key": "Address",
                    "isValid": false
                },
                {
                    "key": "Category",
                    "isValid": false
                },
                {
                    "key": "DateOfBirth",
                    "isValid": false
                },
                {
                    "key": "DateOfExpiration",
                    "isValid": false
                },
                {
                    "key": "DateOfIssue",
                    "isValid": false
                },
                {
                    "key": "DocumentNumber",
                    "isValid": false
                },
                {
                    "key": "FirstName",
                    "isValid": false
                },
                {
                    "key": "LastName",
                    "isValid": false
                },
                {
                    "key": "Gender",
                    "isValid": false
                },
                {
                    "key": "Nationality",
                    "isValid": true
                },
                {
                    "key": "PersonalCode",
                    "isValid": false
                }
            ]
        },
        "rules": [
            {
                "name": "DocumentNotExpired",
                "status": "Fail",
                "reason": "DocumentExpirationDateNotFound"
            },
            {
                "name": "DocumentHasFace",
                "status": "Fail",
                "reason": "DocumentHasNoFace"
            },
            {
                "name": "DocumentHasBothSides",
                "status": "Fail",
                "reason": "DocumentPartTypeNotRecognized"
            },
            {
                "name": "DocumentTypeNotProhibited",
                "status": "Success"
            },
            {
                "name": "NotUnder18",
                "status": "Fail",
                "reason": "BirthDateNotFound"
            },
            {
                "name": "NotProhibitedByCountryOrState",
                "status": "Fail",
                "reason": "DocumentCountryOrStateUnknown"
            }
        ],
        "registries": [],
        "fraudChecks": [],
        "completedUtc": "2023-02-16T14:43:47Z"
    },
    "type": "KycIdentification.Updated"
}

5️⃣ `KycIdentification.Rejected`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the KYC identification is manually or automatically rejected.

For this webhook type, the payload body depends on the KYC ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYC ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "832f67ab-0f6f-4a57-bfc2-83abb543bbd0"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "15df07d7-4b54-4674-9dd5-00354e6cd1a9",
    "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
    "createdUtc": "2023-02-15T15:10:07.6788678Z",
    "payload": {
        "id": "832f67ab-0f6f-4a57-bfc2-83abb543bbd0",
        "applicationId": "8921c61b-a5c0-4f1f-9d44-5a83009a29b1",
        "createdUtc": "2023-02-15T15:09:57.944Z",
        "setup": {
            "id": "d4915b8c-f4a7-4e94-a2c3-16c68a1aee78",
            "versionId": "f3135842-d53c-4525-8118-be63a12641ba"
        },
        "identityVerificationId": "0458600b-f373-404d-8603-9fcc5c8d5d23",
        "status": "Rejected",
        "statusReason": "UnrelatedPhotoSubmit",
        "isCrossChecked": true,
        "document": {
            "type": "Passport",
            "mrzVerified": true,
            "files": [
                {
                    "createdUtc": "2023-02-15T15:09:59Z",
                    "fileId": "df72c1a0-cb92-43d5-9c32-f15ead7a6c83",
                    "fileName": "832f67ab0f6f4a57bfc283abb543bbd0_front_150958998.png",
                    "fileExtension": "png",
                    "part": "FrontCover",
                    "fileType": "DocumentPhoto"
                }
            ],
            "ocrValidations": [
                {
                    "key": "Address",
                    "isValid": true
                },
                {
                    "key": "Category",
                    "isValid": true
                },
                {
                    "key": "DateOfBirth",
                    "isValid": false
                },
                {
                    "key": "DateOfExpiration",
                    "isValid": false
                },
                {
                    "key": "DateOfIssue",
                    "isValid": false
                },
                {
                    "key": "DocumentNumber",
                    "isValid": false
                },
                {
                    "key": "FirstName",
                    "isValid": false
                },
                {
                    "key": "LastName",
                    "isValid": false
                },
                {
                    "key": "Gender",
                    "isValid": false
                },
                {
                    "key": "Nationality",
                    "isValid": false
                },
                {
                    "key": "PersonalCode",
                    "isValid": false
                }
            ]
        },
        "rules": [
            {
                "name": "DocumentNotExpired",
                "status": "Fail",
                "reason": "DocumentExpirationDateNotFound"
            },
            {
                "name": "DocumentHasFace",
                "status": "Fail",
                "reason": "DocumentHasNoFace"
            },
            {
                "name": "DocumentHasBothSides",
                "status": "Fail",
                "reason": "DocumentPartTypeNotRecognized"
            },
            {
                "name": "DocumentTypeNotProhibited",
                "status": "Success"
            },
            {
                "name": "NotUnder18",
                "status": "Fail",
                "reason": "BirthDateNotFound"
            },
            {
                "name": "NotProhibitedByCountryOrState",
                "status": "Fail",
                "reason": "DocumentCountryOrStateUnknown"
            }
        ],
        "registries": [],
        "fraudChecks": [],
        "completedUtc": "2023-02-15T15:10:02Z"
    },
    "type": "KycIdentification.Rejected"
}

🏢 KYB identification webhooks

1️⃣ `KybIdentification.Created`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when the customer has completed filling out the business onboarding form.

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "d91b5007-4af7-4980-8c48-b9658826673e"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "019346d0-770c-47a5-b693-049a79d19c51",
    "applicationId": "0068a566-b5d2-46f1-b5c3-22fdf895953a",
    "createdUtc": "2023-01-02T14:08:01.4572198Z",
    "payload": {
        "id": "d91b5007-4af7-4980-8c48-b9658826673e",
        "createdUtc": "2023-01-02T14:08:01.02",
        "setup": [],
        "applicationId": "0068a566-b5d2-46f1-b5c3-22fdf895953a",
        "legalEntity": {
            "name": "Test company SmartId 2",
            "code": "401038386"
        },
        "verificationFormId": "a632cc2d-2717-4183-bee0-1efe1c868904",
        "identityVerificationId": "00000000-0000-0000-0000-000000000000",
        "representatives": [
            "37cab687-a53c-4228-a1ad-d3cac0bcaac7",
            "28e92146-d3e3-443c-8d4e-50471481cbfe"
        ],
        "status": "Pending",
        "lastStatusChangedUtc": "2023-01-02T14:08:01.02"
    },
    "type": "KybIdentification.Created"
}

2️⃣ `KybIdentification.Approved`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when all KYC identifications have been approved and all registry checks have been successfully validated.

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "dc81eb25-8ccb-4ea9-9dde-c8b46e2f12d1"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "54ec3990-4bfb-40d2-84c1-080ba15be61f",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-14T16:38:01.6026518Z",
    "payload": {
        "id": "dc81eb25-8ccb-4ea9-9dde-c8b46e2f12d1",
        "createdUtc": "2022-12-13T15:55:45.983",
        "setup": {
            "id": null,
            "versionId": null
        },
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "legalEntity": {
            "name": "\u041e\u041e\u041e\u041e\u041e\u041e\u041e",
            "code": "\u041e\u041e\u041e\u041e\u041e\u041e\u041e"
        },
        "verificationFormId": null,
        "identityVerificationId": "a586a568-b464-420f-a7b3-368f2f208b33",
        "representatives": [
            "aea305f5-6123-4f1f-a266-535955e2584d",
            "e118640c-7e5d-471d-83e7-8cfc43504a03"
        ],
        "status": "Approved",
        "statusReason": null,
        "statusDescription": null,
        "lastStatusChangedUtc": "2022-12-14T16:38:01.53"
    },
    "type": "KybIdentification.Approved"
}

3️⃣ `KybIdentification.Rejected`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when not all KYC identifications have been approved and/or when not all registries have been successfully validated.

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/identifications/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/identifications/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "dc81eb25-8ccb-4ea9-9dde-c8b46e2f12d1"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "cbc8f716-425e-4519-990a-584023f9c880",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-14T16:23:50.0805263Z",
    "payload": {
        "id": "dc81eb25-8ccb-4ea9-9dde-c8b46e2f12d1",
        "createdUtc": "2022-12-13T15:55:45.983",
        "setup": {
            "id": null,
            "versionId": null
        },
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "legalEntity": {
            "name": "\u041e\u041e\u041e\u041e\u041e\u041e\u041e",
            "code": "\u041e\u041e\u041e\u041e\u041e\u041e\u041e"
        },
        "verificationFormId": null,
        "identityVerificationId": "a586a568-b464-420f-a7b3-368f2f208b33",
        "representatives": [
            "aea305f5-6123-4f1f-a266-535955e2584d",
            "e118640c-7e5d-471d-83e7-8cfc43504a03"
        ],
        "status": "Rejected",
        "statusReason": "DataNotMatch",
        "statusDescription": null,
        "lastStatusChangedUtc": "2022-12-14T16:23:50.033"
    },
    "type": "KybIdentification.Rejected"
}

4️⃣ `KybIdentification.Document.Created`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when a KYB-related document entity is created in the KYB identification with the status "NeedReview."

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/documents/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/documents/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "701ded06-f832-45f3-9a66-4378d0ba55ed"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "696ec22d-304a-412a-b719-6eeca663e5fe",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-12T10:12:59.4204Z",
    "payload": {
        "id": "701ded06-f832-45f3-9a66-4378d0ba55ed",
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "identificationId": "eccae495-46fb-4f2c-9eba-863f5f407fb0",
        "createdUtc": "2022-12-12T10:12:59.4121043Z",
        "lastActionUtc": "2022-12-12T10:12:59.4121045Z",
        "lastStatusChangedUtc": null,
        "fileId": null,
        "status": "NeedReview",
        "purpose": "ExternalRegistry",
        "title": "SkyNet.pdf"
    },
    "type": "KybIdentification.Document.Created"
}

5️⃣ `KybIdentification.Document.Uploaded`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when a KYB-related document file is uploaded to the document entity.

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/documents/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/documents/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "dd8e3b9e-bece-4b79-8c0d-e74412c19067"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "5d9a674a-1d28-45f1-a7fd-cfe920bbdf21",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-12T12:59:33.146706Z",
    "payload": {
        "id": "dd8e3b9e-bece-4b79-8c0d-e74412c19067",
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "identificationId": "85edabe9-3902-483a-9533-f5d48a842d42",
        "createdUtc": "2022-12-12T12:59:32.303",
        "lastActionUtc": "2022-12-12T12:59:33.123",
        "lastStatusChangedUtc": null,
        "fileId": "kybid-29b125e08eb8410ea9234de3371f665a",
        "status": "NeedReview",
        "purpose": "ExternalRegistry",
        "title": "SkyNet.pdf"
    },
    "type": "KybIdentification.Document.Uploaded"
}

6️⃣ `KybIdentification.Document.Updated`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when a KYB-related document is verified, and the status changes from "NeedReview" to "Validated" or "Invalidated".

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/documents/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/documents/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "ef0dbfa6-5533-4463-a4a8-493aeff7d942"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "21e2e190-bc8b-43ef-914f-3c8ab630d2fa",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-13T09:46:15.6314497Z",
    "payload": {
        "id": "ef0dbfa6-5533-4463-a4a8-493aeff7d942",
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "identificationId": "53953073-3acb-4062-bb34-e2830b01d86d",
        "createdUtc": "2022-12-11T09:49:49.35",
        "lastActionUtc": "2022-12-13T09:46:15.58",
        "lastStatusChangedUtc": "2022-12-13T09:46:15.577",
        "fileId": "kybid-f1126a9b929d4bd2ba1249058140eb52",
        "status": "Invalidated",
        "purpose": "ExternalRegistry",
        "title": "backend (19).txt"
    },
    "type": "KybIdentification.Document.Updated"
}

7️⃣ `KybIdentification.Document.Deleted`

Panel

panelIconId	atlassian-light_bulb_on
panelIcon	:light_bulb_on:
panelIconText	:light_bulb_on:
bgColor	#E6FCFF

The webhook is triggered when a KYB-related document is deleted from KYB identification.

For this webhook type, the payload body depends on the KYB ID API →
Status
colour Blue
title get
/v1/documents/{id} contract.
You can call KYB ID API by using “id” →
Status
colour Blue
title get
/v1/documents/{id} to retrieve the information about the user session.

Expand

title	Reference from the Webhook payload

Code Block

language	json

{
    "payload": {
        "id": "701ded06-f832-45f3-9a66-4378d0ba55ed"
    }
}

Expand

title	Webhook example

Code Block

language	json

{
    "id": "29cbf14a-9baf-40a1-ba05-e9cf0ed8dee7",
    "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
    "createdUtc": "2022-12-12T10:15:08.4286841Z",
    "payload": {
        "id": "701ded06-f832-45f3-9a66-4378d0ba55ed",
        "applicationId": "5d2567dc-1e4e-44bc-a651-7f330a80bd23",
        "identificationId": "eccae495-46fb-4f2c-9eba-863f5f407fb0",
        "createdUtc": "2022-12-12T10:12:59.413",
        "lastActionUtc": "2022-12-12T10:13:00.57",
        "lastStatusChangedUtc": null,
        "fileId": "kybid-2aa9a9c735894ecdabd1451471a604aa",
        "status": "NeedReview",
        "purpose": "ExternalRegistry",
        "title": "SkyNet.pdf"
    },
    "type": "KybIdentification.Document.Deleted"
}

Version	Old Version 58	New Version 59
Changes made by	Priit Aavik	Svajunas
Saved on	Mar 19, 2024	Apr 18, 2024

Versions Compared

Key

ℹ️ About webhooks

🔐 Security

🛒 Ordering

📫 Webhook IP addresses

🔃 Retry logic

❔ How to start receiving webhooks?

😶‍🌫️ Requirements for webhook endpoint

Handling webhooks events with HMAC Authentication

🪄 Webhook types

🆔 Identity Verification (IDV) webhooks

1️⃣ `IdentityVerification.StatusChanged`

2️⃣ `IdentityVerification.Consented`

👤 KYC Identification webhooks

1️⃣ `KycIdentification.Created`

2️⃣ `KycIdentification.Processed`

3️⃣ `KycIdentification.Approved`

4️⃣ `KycIdentification.Updated`

5️⃣ `KycIdentification.Rejected`

🏢 KYB identification webhooks

1️⃣ `KybIdentification.Created`

2️⃣ `KybIdentification.Approved`

3️⃣ `KybIdentification.Rejected`

4️⃣ `KybIdentification.Document.Created`

5️⃣ `KybIdentification.Document.Uploaded`

6️⃣ `KybIdentification.Document.Updated`

7️⃣ `KybIdentification.Document.Deleted`

Content Comparison

Versions Compared

Key

ℹ️ About webhooks

🔐 Security

🛒 Ordering

📫 Webhook IP addresses

🔃 Retry logic

❔ How to start receiving webhooks?

😶‍🌫️ Requirements for webhook endpoint

Handling webhooks events with HMAC Authentication

🪄 Webhook types

🆔 Identity Verification (IDV) webhooks

1️⃣ IdentityVerification.StatusChanged

2️⃣ IdentityVerification.Consented

👤 KYC Identification webhooks

1️⃣ KycIdentification.Created

2️⃣ KycIdentification.Processed

3️⃣ KycIdentification.Approved

4️⃣ KycIdentification.Updated

5️⃣ KycIdentification.Rejected

🏢 KYB identification webhooks

1️⃣ KybIdentification.Created

2️⃣ KybIdentification.Approved

3️⃣ KybIdentification.Rejected

4️⃣ KybIdentification.Document.Created

5️⃣ KybIdentification.Document.Uploaded

6️⃣ KybIdentification.Document.Updated

7️⃣ KybIdentification.Document.Deleted

1️⃣ `IdentityVerification.StatusChanged`

2️⃣ `IdentityVerification.Consented`

1️⃣ `KycIdentification.Created`

2️⃣ `KycIdentification.Processed`

3️⃣ `KycIdentification.Approved`

4️⃣ `KycIdentification.Updated`

5️⃣ `KycIdentification.Rejected`

1️⃣ `KybIdentification.Created`

2️⃣ `KybIdentification.Approved`

3️⃣ `KybIdentification.Rejected`

4️⃣ `KybIdentification.Document.Created`

5️⃣ `KybIdentification.Document.Uploaded`

6️⃣ `KybIdentification.Document.Updated`

7️⃣ `KybIdentification.Document.Deleted`