Overview

• Webhook Notification provides a secure, signed, asynchronous event delivery mechanism for Identity Verification Solution.
• Webhook notifications are used when the callback URL is not provided in API requests.
• All webhook requests are signed to ensure authenticity, integrity, and replay protection.

⚠️

Webhook delivery is not guaranteed.

Clients must implement polling to retrieve final results if webhook delivery fails.

We recommend a polling interval of 10 minutes or greater.

Webhook Endpoint Requirements

Clients must provide an HTTPS endpoint capable of receiving webhook notifications.

Network & Security

• Only HTTPS endpoints are supported
  HTTP endpoints are not allowed
• Supported TLS versions:
  • TLS 1.2 or higher

HTTP Request

Retry Policy

If a webhook request fails, the system retries delivery automatically.

Failure Conditions

• Network error
• Request timeout (> 60 seconds)
• Any non-2xx HTTP response

Retry Schedule

Webhooks follow an at-least-once delivery model. Clients must handle duplicate events safely.

Webhook Configuration

Webhook configuration is currently managed offline. To create or update a webhook, please contact our administrators and provide:

• Webhook HTTPS URL
• Customer / Account information
• Shared secret key (secretKey) for request signing

Webhook self-service management is under development.

Content Signature

All webhook requests are signed using a shared secret.

Supported Signature Algorithms

• HMAC-SHA256
• HMAC-SHA512

Signature Headers

Signature Content

To avoid ambiguity, the signature content is constructed in a fixed order with newline separators:

stringToSign = JSON.stringify(requestBody)

Signature Generation

signature = Base64(HMAC_SHA256(secretKey, stringToSign))

Signature Verification (Client Side)

Clients must verify webhook requests before processing.

Step 1: Read Headers

timestamp = aai-timestamp
nonce = aai-nonce
signature = aai-signature

Step 2: Validate Timestamp

• The timestamp must be within ±5 minutes of current time
• Requests outside this window must be rejected

Step 3: Validate Nonce

• Each nonce must be unique
• Recommended: cache nonce values for 5 minutes
• If the nonce is reused, reject the request

Step 4: Recalculate Signature

serverSignature = Base64(
  HMAC_SHA256(secretKey, requestBody)
)

Step 5: Compare Signatures

• If signatures do not match → reject with HTTP 400 / 401

Step 6: Respond

Event Format

Event Example

{
  "eventId": "uuid",
  "eventIype": "COMPLETED",
  "data": {
    "signatureId": "1234567890",
    "type": "COMPLETED"
  }
}

{
    "eventId": "uuid",
    "eventIype": "KYB_COMPANY_CHECK_STATUS",
    "data": {
        "id": "KYBC-201464826803499999",
        "vendorId": "49f72e01-e1fa-48ef-8129-87c90a66666",
        "status": "COMPLETED",
        "updatedAt": 1769405823
    }
}

{
    "eventId": "uuid",
    "eventIype": "AML_OGS_UPDATE",
    "data": {
      "profileId": "PF_R5BoIxxxxxxxxxxQnnNVqi",
      "caseId": 1998600000000026050,
      "alertId": 2001680000000082882,
      "numberOfNewResults": 0,
      "numberOfUpdatedResults": 1
    }
}

Event Fields

Event Types