Skip to main content

IDNorm Integration Guide

Get ready to automate your identity verification flows. This guide will walk you through the three core steps to get your integration up and running.

Prefer Manual? No Problem! If you don't need automation, just log in to the IDNorm Platform, create your flows, and share the verification links directly.

⚙️ Your Automation Blueprint​

Programmatic integration is a 3-step process. We'll create verification sessions on-demand and get notified securely when they're complete.

  1. API Call: Create a user session.
  2. Callback: Redirect the user back to your app.
  3. Webhook: Get real-time status updates from our platform.

Here is a full sequence diagram illustrating the flow.

Legend:

  • User: The end-user interacting with the verification flow.
  • Idnorm Platform: The Idnorm platform handling the verification process.
  • Client App: The client (yours) application integrating with Idnorm.

Step 1: Create a Session via API​

To kick off a verification, you'll make a POST request to our CreateSession (/api/v1/create_session) endpoint. This generates a unique verification URL for your user.

See the full spec in the Platform API Docs.

Request Parameters​

ParameterRequired?Description
configId✅ YesThe ID of the verification flow you configured on the platform.
callbackUrl❌ NoURL to redirect the user to after they finish. Crucial for a smooth UX!
externalUserId❌ NoYour internal user ID. Use this to link the session back to a user in your system.
durationInSeconds❌ NoHow long the session link is valid. Defaults to 3 days (259200 seconds).

Step 2: Configure Your Webhook​

To receive real-time updates on verification status, you need to set up a webhook.

  1. Navigate to Verifications -> Settings on the platform.
  2. Set your Webhook URL (the endpoint in your application that will listen for our events).
  3. Generate and copy your Webhook Secret.

🔐 Your Webhook Secret is Critical! This key is used to verify that incoming webhook requests are genuinely from IDNorm. Keep it secure and never expose it on the client-side.

Step 3: Implement & Secure Your Webhook Listener​

When a verification status changes, we'll send a POST request to your webhook URL. Your job is to listen, verify, and act on that data.

⚠️ Webhook Delivery & Retry Policy If your webhook endpoint is down or returns a non-2xx status code, IDNorm will automatically retry the request. We'll attempt delivery multiple times with exponential backoff to ensure you receive critical verification updates. Make sure your endpoint is robust and returns appropriate HTTP status codes.

The Security Handshake: Idnorm-Signature​

Every webhook request includes an Idnorm-Signature header. You must validate this signature to prevent forged requests.

The header format is simple: timestamp.hmac_sha256_signature

Example: 1672531200.a1b2c3d4e5f6...

The signature is created by hashing the timestamp and the raw request body with your webhook secret. Your server must perform the exact same calculation to verify its authenticity.

Request body To decode the request body please refer to API documentation where you can download the OpenAPI specification and find the detailed request body schema.

🛡️ HMAC Signature Verification: Code Snippets​

Here are plug-and-play functions to handle the signature verification.

Pseudocode: The Logic Explained​

If your language isn't listed, follow these steps.

  1. 🔍 Parse Header: Split the Idnorm-Signature header at the . to get the timestamp and the receivedSignature.
  2. ⏰ Check Timestamp: Ensure the timestamp is recent (e.g., within the last 5 minutes) to prevent replay attacks. This is a critical security step!
  3. 🔑 Prepare Data:
    • Convert the received timestamp into an 8-byte array.
    • Concatenate the timestamp bytes with the raw requestPayload.
  4. 🛡️ Generate Signature: Compute an HMAC-SHA256 hash of the prepared data using your webhookSecret.
  5. ✅ Compare: Use a constant-time comparison function to check if your generated signature matches the receivedSignature. If they match, the request is authentic.