Webhooks

Overview

pawaPass sends webhook notifications to your configured URL when verification events occur. This allows you to track the entire lifecycle of a verification in real-time.

Setup

You can configure your webhook target URL and signing secret in the Backoffice (Production, Sandbox). Each environment is configured separately.

Events

VERIFICATION.STATUS_CHANGE

Sent each time a verification’s status changes, from CREATED through STARTED, USER_DATA_COLLECTED, to a final state like APPROVED or DECLINED.This is the primary webhook for monitoring verification progress.

VERIFICATION.IDENTITY_DOCUMENT_CHANGE

Sent when an agent manually corrects identity document data after a verification has concluded (e.g., fixing a typo in a name or date of birth).Does not fire during initial data collection.

Payload format

All webhook payloads follow the same structure:

{
  "notificationId": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "type": "VERIFICATION.STATUS_CHANGE",
  "object": "VERIFICATION",
  "createdAt": "2025-08-20T10:15:00.000Z",
  "data": {
    "id": "aB1cD2eF",
    "externalId": "user-zm-98765",
    "requirements": [
      { "type": "FACE_SCAN" },
      { "type": "DOCUMENT_SCAN" }
    ],
    "url": "https://app.pawapass.com/your-company/aB1cD2eF",
    "status": "APPROVED",
    "country": "ZM",
    "phoneNo": "+260971234567",
    "workflowId": "wf3kD9aB",
    "reviewResult": null,
    "metadata": {
      "reason": "kyc-onboarding",
      "channel": "mobile-app",
      "department": "compliance"
    },
    "successUrl": "https://your-website.com/success",
    "errorUrl": "https://your-website.com/error",
    "supportUrl": "https://your-website.com/support",
    "identityDocument": {
      "type": "NATIONAL_ID",
      "country": "ZM",
      "serialNo": "9876543/21/1",
      "nationalNo": "Z12345678",
      "firstName": "Tisa",
      "lastName": "Banda",
      "dateOfBirth": "1997-05-10",
      "placeOfBirth": "Lusaka",
      "nationality": "ZM",
      "expiryAt": "2032-05-09",
      "issuedAt": "2022-05-10",
      "issuingAuthority": "Republic of Zambia",
      "placeOfIssue": "Lusaka",
      "createdAt": "2025-08-20T09:31:00.000Z",
      "updatedAt": "2025-08-20T10:15:00.000Z"
    },
    "faceScan": {
      "ageEstimation": "OVER_25",
      "createdAt": "2025-08-20T09:30:00.000Z",
      "updatedAt": "2025-08-20T09:31:15.000Z"
    },
    "createdBy": "[email protected]",
    "expiresAt": "2025-08-27T09:00:00.000Z",
    "createdAt": "2025-08-20T09:00:00.000Z",
    "updatedAt": "2025-08-20T10:15:00.000Z"
  }
}

Field reference

Field	Type	Description
`country`	`string \| null`	ISO 3166-1 alpha-2 country code associated with this verification.
`phoneNo`	`string \| null`	Phone number associated with this verification.
`workflowId`	`string \| null`	shortId of the workflow running this verification. `null` until the workflow is pinned: a verification created with neither `workflowId` nor `requirements` runs on the country default and is pinned when it starts, so this is `null` on the `CREATED` event and set from `STARTED` onward. Also `null` for verifications created before pawaPass stored the workflow, or before workflows existed.
`reviewResult`	`object \| null`	Review outcome details. `null` when the verification has not been reviewed or no review reason is available. When present, contains `category`, `reason`, and `sensitive`.

Review result object

When reviewResult is present, it has the following fields:

Field	Type	Description
`category`	`string \| null`	Decline reason category code (see below). `null` for legacy reasons without a category.
`reason`	`string`	Specific decline reason code (e.g. `ONE_SIDE_MISSING`, `DOCUMENT_EXPIRED`, `DOCUMENT_FAKE`).
`sensitive`	`boolean`	Whether the decline reason is flagged sensitive. When `true`, avoid exposing the specific reason to the end user.

Example for a declined verification:

"reviewResult": {
  "category": "CAPTURE_ISSUE",
  "reason": "IMAGE_BLURRY",
  "sensitive": false
}

Review result categories

`category`	Description
`CAPTURE_ISSUE`	Problem with the document capture (e.g. missing side, blurry photo, poor lighting).
`DOCUMENT_VALIDITY`	The document could not be validated (e.g. expired, wrong type, photocopy).
`DOCUMENT_VALIDITY_CONCERN`	Suspected document authenticity issue. Flagged sensitive.
`IDENTITY_VERIFICATION`	Identity could not be confirmed (e.g. name or face mismatch). Flagged sensitive.
`SYSTEM_PROCESS`	System or process related decline (e.g. duplicate submission). Flagged sensitive.
`OTHER`	Other reason captured as free text. Flagged sensitive.

Review result reasons

The default reason codes in pawaPass, grouped by category. The set may be extended over time, so treat unknown codes gracefully and branch on category and sensitive where possible.

`category`	`reason`	`sensitive`	Meaning
`CAPTURE_ISSUE`	`ONE_SIDE_MISSING`	`false`	One side of document is missing
`CAPTURE_ISSUE`	`DOCUMENT_EDGES_CUT_OFF`	`false`	Document edges cut off
`CAPTURE_ISSUE`	`IMAGE_BLURRY`	`false`	Image is blurry
`CAPTURE_ISSUE`	`POOR_LIGHTING`	`false`	Poor lighting (too dark, bright, or flash glare)
`CAPTURE_ISSUE`	`LOW_IMAGE_QUALITY`	`false`	Low image quality
`CAPTURE_ISSUE`	`TEXT_UNREADABLE`	`false`	Text on document unreadable
`DOCUMENT_VALIDITY`	`INVALID_DOCUMENT_TYPE`	`false`	Invalid document type
`DOCUMENT_VALIDITY`	`DOCUMENT_EXPIRED`	`false`	Document expired
`DOCUMENT_VALIDITY`	`DOCUMENT_DAMAGED`	`false`	Document physically damaged or worn out
`DOCUMENT_VALIDITY`	`REQUIRED_FIELD_MISSING`	`false`	Required field missing on document
`DOCUMENT_VALIDITY`	`PHOTOCOPY_DETECTED`	`false`	Photocopy or printed copy detected
`DOCUMENT_VALIDITY`	`SCREENSHOT_DETECTED`	`false`	Screenshot detected
`DOCUMENT_VALIDITY_CONCERN`	`DOCUMENT_FAKE`	`true`	Document appears fake or forged
`IDENTITY_VERIFICATION`	`NAME_MISMATCH`	`true`	Name does not match
`IDENTITY_VERIFICATION`	`FACE_MISMATCH`	`true`	Face does not match document photo
`IDENTITY_VERIFICATION`	`SUSPECTED_THIRD_PARTY_VERIFICATION`	`true`	Suspected the applicant is not the true account operator
`SYSTEM_PROCESS`	`DUPLICATE_SUBMISSION`	`true`	Duplicate submission detected
`OTHER`	`DECLINE_OTHER`	`true`	Other reason captured as free text

Age estimation values

The ageEstimation field on the face scan can be one of:

Value	Age
`UNDER_8`	Under 8 years
`OVER_8`	Over 8 years
`OVER_13`	Over 13 years
`OVER_16`	Over 16 years
`OVER_18`	Over 18 years
`OVER_21`	Over 21 years
`OVER_25`	Over 25 years
`OVER_30`	Over 30 years
`UNKNOWN`	Could not be estimated

Signature verification

Webhooks include an X-SIGNATURE header containing a SHA256 HMAC signature of the raw request body, signed with your secret key. Verify this signature to confirm the webhook is authentic.

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(
  requestBody: string,
  signature: string,
  secretKey: string
): boolean {
  const expected = createHmac('sha256', secretKey)
    .update(requestBody, 'utf-8')
    .digest('hex');
  const expectedBuf = Buffer.from(expected, 'hex');
  const signatureBuf = Buffer.from(signature, 'hex');
  return (
    expectedBuf.length === signatureBuf.length &&
    timingSafeEqual(expectedBuf, signatureBuf)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = verifyWebhookSignature(req.rawBody, signature, SECRET_KEY);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.rawBody);
  // Process the webhook...

  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook_signature(request_body: bytes, signature: str, secret_key: str) -> bool:
    expected = hmac.new(
        secret_key.encode('utf-8'),
        request_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Best practices

Verify the signature

Always validate the X-SIGNATURE header before processing the webhook payload.

Return 200 OK quickly

Process the webhook asynchronously if needed. Any non-2xx response triggers retries.

Handle duplicate deliveries

Use the notificationId field to deduplicate. Webhooks may be retried.

Route by event type

Use the type field to determine how to process each event.

Secret rotation

Legacy integrations used a single shared secret for both API authentication and webhook signing. If you have not yet rotated your webhook secret, the legacy secret is still used for signing. Rotating the webhook secret does not affect your API key, and vice versa. These are now fully independent.

Only one webhook secret may be active at a time, so rotating it requires coordination with your application. To rotate:

Prepare your application to accept the new secret.
Generate a new secret in the Backoffice and update your application at the same time.
Verify that incoming webhooks pass signature validation.

There may be a short window where some webhook deliveries fail signature validation on your side due to the timing mismatch. These will be retried automatically using the normal retry schedule (see below), so no notifications will be lost.

Retries

If your endpoint returns a non-2xx status code or times out, pawaPass will retry delivery using capped exponential backoff with jitter:

55 attempts over approximately 1 week
Delay starts at 1 second, doubles each time (1s, 2s, 4s, 8s, …), capped at 4 hours
Each delay includes ±25% random jitter to prevent thundering herd
If all retries are exhausted, the notification is dropped

Use List verifications or Get verification to poll for missed updates.

Get Started

Guides

Overview

Setup

Events

Payload format

Field reference

Review result object

Review result categories

Review result reasons

Age estimation values

Signature verification

Best practices

Secret rotation

Retries

​Overview

​Setup

​Events

​Payload format

​Field reference

​Review result object

​Review result categories

​Review result reasons

​Age estimation values

​Signature verification

​Best practices

​Secret rotation

​Retries

Overview

Setup

Events

Payload format

Field reference

Review result object

Review result categories

Review result reasons

Age estimation values

Signature verification

Best practices

Secret rotation

Retries