Webhooks

Real ID will emit webhooks in real time throughout the ID verification lifecycle.

Use these webhooks to synchronize your customer data with their current ID check status, or to hold and release orders by verified customers.

note

This feature is for Enterprise customers only.

To unlock this feature and upgrade to an Enterprise subscription, please contact us.

ID check events

Real ID will emit HTTP webhooks during the following events:

• check.delivered - the ID check is initially created.
• check.opened - the customer opens the ID check.
• check.submitted-photo - the ID check receives a photo from the customer.
• check.completed - the customer successfully completes the ID check.
• check.failed - the customer fails the ID check.

Check Event Data

Webhooks are sent as POST requests and include a JSON body. Below is an example of a check.created event:

{
  "event": "check.created",
  "created_at": "2022-12-09T15:20:35.136Z",
  "check": {
    "id": "abcdef",
    "step": "delivered",
    "testing": true
  }
}

Status changes

Below is a state diagram that illustrates how the ID check statuses change through the ID check lifecycle:

note

Some steps will affect with overall verdict even though more photos might be required and the check is in progress.

For example, if the customer's ID photo is missing required fields or is unreadable, then even if the face match passes, the overall ID check would be a failure.

Privacy events

Customers can contact Real ID directly regarding their ID checks. Real ID is a processor of your customer data, it does not act on these requests directly.

As a controller, you can subscribe to these webhooks for notifications on the following privacy related events:

• customer.data_request - A customer has requested a copy of all of their data.
• customer.manual_review_requested - A customer has requested a manual review of their ID check results.
• customer.data_deletion_request - A customer has requested to have their data deleted.

Privacy Event Data

Webhooks are sent as POST requests and include a JSON body. Below is an example of a customer.data_request event:

{
  "event": "customer.data_request",
  "created_at": "2022-12-09T15:20:35.136Z",
  "check": {
    "id": "abcdef",
    "testing": true
  }
}

tip

Use the included check.id in the response to query the full check data with the retrieve a check API endpoint.

Defining Webhook URLs

You can define a webhook URL for accepting each of these events within the Settings > DevTools area of the app.

All events contain the unique check ID, the event name, and the check data.

Verifying Webhooks

The webhook HTTP request contains a X-Real-ID-Signature header that will need to be verified for authenticity.

Use your Signing Secret from the Real ID dashboard to sign the request's body to ensure that the request is originating from Real ID.

Node.js

const crypto = require("crypto");

function verifyWebhookSignature(payload, headers) {
  // The signature included in the request headers
  signature = headers["x-real-id-signature"];

  // The webhook private signing key you can find within the Real ID app settings
  secret_key = process.env.REAL_ID_SIGNING_KEY;

  // Compute the HMAC signature using the provided secret key and payload
  const computedSignature = crypto
    .createHmac("sha256", secretKey)
    .update(JSON.stringify(payload))
    .digest("hex");

  // Compare the computed signature with the one included in the request headers
  if (computedSignature === signature) {
    console.log("Webhook signature is valid");
  } else {
    console.log("Webhook signature is invalid");
  }
}

Python

import os
import hmac
import hashlib
import json

def verify_webhook(body, headers):
  # NOTE: by default, Python's json.dumps returns additional pretty printing that will introduce whitespace not included during generation
  # Remove extra whitespace if using json.dumps as the payload body
  # If you're using Flask, use the `request.get_data()` method to retrieve the raw body
  payload = json.dumps(body, separators=(',', ':'))

  # The signature included in the request headers
  signature = headers["x-real-id-signature"]

  # The webhook private signing key you can find within the Real ID app settings
  secret_key = os.environ.get('REAL_ID_SIGNING_KEY')

  # Compute the HMAC signature using the provided secret key and payload
  computed_signature = hmac.new(
      key=bytes(secret_key, 'utf-8'),
      msg=bytes(payload, 'utf-8'),
      digestmod=hashlib.sha256
  ).hexdigest()

  # Compare the computed signature with the one included in the request headers
  if computed_signature == signature:
      return True
  else:
      return False

The shape of data is the same across the other events, only the event and the check.step will change from event type to event type.

warning

For security purposes, not all data associated with the ID check is included in the webhook.

To retrieve all details, make a request to the GET check API endpoint with the unique check ID included.

Network Range

Webhooks can be requested from any IP address within the AWS us-east-1 region.

To view all available IP addresses, please see AWS's IP range documentation here: https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html