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"
}