Webhook Specifications

Get all verification data straight in your backend system

Tracking the MetaMap verification


Describes the different events in the verification life cycle.


"eventName": "verification_started"

Possible eventName values are:

  • verification_started
  • step_completed
  • verification_inputs_completed
  • verification_completed
  • verification_updated


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"


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 the step id values are:

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

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


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.


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


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


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"


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

"flowId": "60b8fd58a87c31111b14dedc"


When the webhook was sent.

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


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 and code.

Rejected: Fraud Attempt

The following example shows a document check that MetaMap has flagged as possible fraud.

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

Review Needed: Negligence

The following example shows a document check that MetaMap has flagged for manual review.

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

Did this page help you?