Webhook Specifications

Get all verification data straight in your backend system

Tracking the Trust Experience

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 Trust Experience 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

verification_inputs_completed

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

verification_completed

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


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

Rejected: Fraud Attempt

The following example shows a document check that Mati 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 Mati 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?