Tracking the MetaMap verification

`eventName`

Describes the different events in the verification life cycle.

Example:

"eventName": "verification_started"

Possible eventName values are:

verification_started
step_completed
verification_inputs_completed
verification_completed
verification_updated

`verification_started`

The verification process began as per the user opening the direct link, launching the experience from the SDK or by calling the Verification Creation endpoint.

{
  "resource": "https://api.getmati.com/v2/verifications/6156311aba4c52001b1290a2",
  "eventName": "verification_started",
  "flowId": "60b8fd58a87c30001b14dedd",
  "timestamp": "2021-09-30T21:50:19.342Z"
}

`step_completed`

Each step in your metamap will trigger a webhook with its own data, so you can track the user's progress through the experience as well as take the data you need as soon as it is available.

These step_completed webhooks have an step object which contains the specific data and the id tag will let you identify the current step.

Some of these id values are:

ip-validation
document-reading
watchlists
premium-aml-watchlists-search-validation
age-check
template-matching
alteration-detection
liveness
voice
facematch

For a full list of id values, go to our Webhook Messages pages where the messages are listed by their id.

Alteration Detection

Documents with an alteration-detection error can have one of two codes:

alterationDetection.fraudAttempt: trigger a rejected verification status
alterationDetection.negligence: trigger a reviewNeeded verification status

`verification_inputs_completed`

The verification_inputs_completed event name let you know that all the inputs required by the metamap were received and MetaMap is working on delivering a final verification status.

`verification_completed`

For each user verification that MetaMap has finished processing (via SDKs or API), Metamap will send you a verification_completed Webhook.

`verification_updated`

From the dashboard you can update the status and the data extracted from the document.

In these cases you will receive a webhook with verification_updated event, which has exactly the same structure as verification_completed.

When updating the status, you will see the new status in the identityStatus field, while the status field is immutable and will always show the originally assigned status.

Status

There are three verification statuses that are processed automatically and apply only when the responses to all the verification steps have completed:

verified: All verification steps have passed with no issues
reviewNeeded: One or more verification steps have issues that require manual review
rejected: One or more verification steps have issues that point to fraud

Both Review Needed and Rejected statuses will be related to the error object in the step_completed webhooks that will include a type, code, and message.

Verification Dashboard URL

The verification_completed webhook contains the key matiDashboardUrl which you can use to directly access a given verification through your browser.

General Outputs

`resource`

All webhooks contain a resource URL that has all the user's verification information. Note that you do not have to wait for the verification_completed webhook to consult it. Just GET it! More information about this request in our Retrieve Webhook Resource Data endpoint.

"resource": "https://api.getmati.com/v2/verifications/6155311aab4c52001b1290a2"

`flowID`

All Webhooks contain the flowId related to the flow the verification belongs to.

"flowId": "60b8fd58a87c31111b14dedc"

`timestamp`

When the webhook was sent.

"timestamp": "2021-10-01T23:23:16.316Z"

`metadata`

The custom values you sent when initiating the verification process as described in our Web SDK documentation .

"metadata": {
    "customTag": "customValue",
    "userId": "564853",
    "campaign": "monday-morning"
  }

Webhook Examples

The following examples show a single step (alteration detection) and code.

{
  "eventName" : "step_completed",
  "step" : {
    "status" : 200,
    "id" : "alteration-detection",
    "error" : {
      "type" : "StepError",
      "code" : "alterationDetection.fraudAttempt",
      "message" : "Document is considered as fraud attempt"
    },
    "documentType": "national-id"
  },
  "resource": "https://api.getmati.com/v2/verifications/601142c648494064cdd70d9a",
  "timestamp": "2021-01-27T10:39:12.348Z",
  "flowId": "5e972984c2b5b0001a8eac13"
}

{
  "eventName": "step_completed",
  "step": {
    "status": 200,
    "id": "alteration-detection",
    "error": {
      "type": "StepError",
      "code": "alterationDetection.negligence",
      "message": "Document is considered as negligence"
    },
    "documentType": "passport"
  },
  "resource": "https://api.getmati.com/v2/verifications/601142c648494064cdd70d9a",
  "timestamp": "2021-01-27T10:39:12.348Z",
  "flowId": "5e972984c2b5b0001a8eac13"
}