NAV Navbar
shell

I. Webhook documentation introduction

This documentation explains how to get users verification information (via webhook) after they finished Mati SDK flow. Note that this documentation is not about Web/Mobile SDK integration.

Few important notes:

Webhook Description
verification_completed Webhook sent once Mati is done verifying a user entirely. When you get this webhook, you should GET the "resource" URL to get the verification data about the user.
verification_started Webhook sent at the beginning of the SDK flow, when Mati is making a new verification record (usually at the upload of the first ID document)

II. How to receive user' verification information

Introduction

Step 1 : Register a webhook URL on your Mati dashboard

If you login to your Mati dashboard, and go the developer section, you will be able to add a new webhook URL. That way Mati knows to what URL it should communicate webhooks related information. You should also add a "webhook secret" (user any string of any length). That assures you that the webhook is indeed coming from Mati.

Step 2: Receive the webhook

Webhook you will receive once user verification is finished

{
  "eventName": "verification_completed",
  "metadata": {
    "user_email": "john.smith@gmail.com",
    "user_name": "john_smith",
    "user_id": "123456789"
  },
  "resource": "https://api.getmati.com/v1/verifications/5c6b534bd3efe73404b52341"
}

You will receive a "verification_completed" webhook. This webhook is sent only once Mati could complete the user verification. This webhook will contain the following fields.

Parameter Description
eventName Webhook type
metadata Metadata that you transmitted to Mati SDKs. You can put any type of metadata here. That way, your backend knows what user just got verified
resource Contains the link you should use in order to get the user verification information

Step 3: Validate webhook signature (optional)

Validate your webhook signature

const crypto = require('crypto');

function verify(signature, secret, payloadBody) {
  const hash = crypto.createHmac('sha256', secret)
    .update(payloadBody).digest('hex');
   return hash === signature;
}

When you create a webhook url on your Mati dashboard, you define a "secret". This "secret" will then be hashed with the "payloadBody" (using SHA256) and sent in the webhook's header. In order to authenticate the webhook received, you should verify that this signature on header 'x-signature' (Signature-Sha-256) is valid. See a code snippet on the right.

Step 4: Get your authentication token

POST request to get a valid token

curl --location --request POST "https://api.getmati.com/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic $(echo -n client_id:client_secret | base64)" \
  --data "grant_type=client_credentials&scope=identity"

In order to be able to fetch the data inside the resource link, you should first get a valid token. To get a new valid token, it'you just need to perform a POST request and pass as parameters your client_id and client_secret available on your Mati dashboard.

Headers Value
Content-Type application/x-www-form-urlencoded
Authorization Basic
Body Value
grant_type client_credentials
score identity

Step 5: GET users' "resource" URL

GET request on the "resource" URL

curl --location --request GET "<your_resource_url>" \
  --header "Authorization: Bearer {{ACCESS_TOKEN}}"

Response sample

{
        "steps": [
            {
                "status": 200,
                "id": "liveness",
                "data": {
                    "selfieUrl": "http://api.getmati.com/media/selfie/bae11202.jpg",
                }
            }
        ],
        "documents": [
            {
                "type": "passport",
                "photos": [
                    "https://api.getmati.com/v1/media/ae7b963c1f23.jpg",
                    "https://api.getmati.com/v1/media/ae7b963c1f2e.jpg"
                ],
                "steps": [
                    {
                        "status": 200,
                        "id": "alteration-detection",
                    },
                    {
                        "status": 200,
                        "id": "document-reading",
                        "data": {
                            "fullName": {
                                "value": "HUGO JOSE FRANCOU"
                            },
                            "documentNumber": {
                                "value": "AAA722873"
                            },
                            "dateOfBirth": {
                                "value": "1950-07-14T00:00:00.000Z"
                            },
                        },  
                    },
                    {
                        "status": 200,
                        "id": "facematch",
                    },
                    {
                        "status": 200,
                        "id": "watchlists",
                    },
                    {
                        "status": 200,
                        "id": "mexican-curp-validation",
                        "data": {
                            "curp": "GAGF860420HDFRMR08",
                            "fullName": "GARCIA GOMEZ FERNANDO ELIAS",
                            "name": "FERNANDO ELIAS"
                    }
                ],
            },
        ],
        "id": "3452455cb0d48780"
    }

If you want to access the user verification data, you need to make a GET request on the "resource" URL contained inside the webhook.

Headers Value
Authorization Basic

The response is organised in a way that it contains verification "steps". These steps are nested. For example step "document-reading" is nested inside step "document"

Steps Type Description
liveness Contains the proof of life response, making sure your user is a real person (and not a printed paper)
document-reading Will return fields read from the document: full name, date of birth, document number, etc...
facematch Face match performed between document face & user's face
watchlists Checks if there is any match found between the name extracted from the document and international watch-lists
alteration-detection Checks that the document was not altered
template-matching Checks that the presented document revision is valid
mexican-curp-validation For certain countries only (only Mexico supported for now)

III. Most frequent questions to integrate Mati

How to automate your verification process with Mati?

You are free to build your own logic, but here is the flow most companies are happy with:

1) Let the user go through Mati SDK

2) Receive the frontend callback to know when the user finished the verification flow

3) Display a beautiful waiting page to the user saying "You are under review. Please come back in a few minutes!"

4) Wait for the "verification_completed" webhook, and parse the verification information

5) If you cannot find any errors inside Mati verification steps, automatically let your user access to your service

6) If Mati found some issues with the verification, you should probably manually check the user

What is allowed to pass to metadata?

What should I put for my "webhook secret"?

Feel free to enter any string of any length. As explained inside section II (step2), we use a webhook secret as a way to assure the authenticity of your webhook. Consider this a password that only you should know.

What happens in case a verification step fails?

Invalid verification step sample (alteration-detection)


{
    "error": {
        "code": 400,
        "message": "document is considered tempered"
    },
    "status": 200,
    "id": "alteration-detection",
},

Invalid verification step sample (liveness)



{
    "error": {
        "code": 400,
        "message": "user did not pass liveness"
    },
    "status": 200,
    "id": "liveness",
    "data": {
        "selfieUrl": "http://api.getmati.com/media/selfie/bae11202.jpg",
    }
}

Invalid verification step sample (mexican-curp-validation)



{
    "error": {
        "code": 400,
        "message": "we could not extract anything from CURP database"
    },
    "status": 200,
    "id": "mexican-curp-validation",
    "data": {
    }
},

Whenever Mati detects any risk while verifying a user, some error will be returned in at least 1 verification step. On the right, the example of some error rendered for some verification steps. So when you parse the user verification data, just try to identify any error inside any verification step. If there's none, you can automate that user verification process, and let him fully access your service.

What happens when Mati cannot read a document field?

It happens that documents are too damaged or blurry to be read. In that case Mati will render 'null' as field value to indicate that we could not read this field.

Document reading response when "documentNumber" and "dateOfBirth" could not be read


...

{
    "status": 200,
    "id": "document-reading", 
    "data": {
        "fullName": {
            "value": "HUGO JOSE FRANCOU"
        },
        "documentNumber": {
            "value": null
        },
        "dateOfBirth": {
            "value": null
        },
    },
},

...

How to download selfie & documents images?

GET request to get any image

curl --location --request GET "<your_image_url>" \
  --header "Authorization: Bearer {{ACCESS_TOKEN}}"

Once you got the verification information, you might want to store the images of selfie and documents on your server. For that, you can simply make a GET request.

Headers Value
Authorization Basic

How to know when a user finished Mati Web SDK?

How to subscribe to Mati Web SDK callback


Mati.on("mati:userFinishedSdk", function (data) {
  console.log("<text>", data._args);
});

Mati Web SDK has 2 callbacks, described below.

Callback Description
mati:userFinishedSdk Callback fired when user clicks "done" button at the very end of Mati Web SDK flow. This indicates that the user has finished uploading all necessary information to Mati.
mati:exitedSdk Callback fired when user exits the Mati Web SDK. This indicates that the user has not finished the verification flow.
shell