Webhooks

For asynchronous verifications — documents, face match and some liveness checks — IdentifyOrg sends the result to your registered webhook URL as soon as processing completes. Register endpoints from your dashboard or via POST /v1/webhooks.

Payload

Every delivery is a JSON POST containing the event type, job ID, result and timestamp:

Webhook payload

{
  "event": "verification.completed",
  "job_id": "job_01hxyz...",
  "created_at": "2026-07-02T10:24:00Z",
  "data": {
    "type": "document",
    "status": "success",
    "document_type": "utility_bill",
    "checks": {
      "date_recent": true,
      "address_extracted": true
    },
    "extracted": {
      "address": "12 Awolowo Road, Ikoyi, Lagos",
      "issuer": "Ikeja Electric",
      "bill_date": "2026-06-14"
    }
  }
}

Verifying signatures

All payloads are signed with HMAC-SHA256 using your webhook secret. The signature arrives in the X-IdentifyOrg-Signature header — always verify it before trusting a payload:

verify_signature.py

import hmac, hashlib

def verify_webhook(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your handler:
# signature = request.headers["X-IdentifyOrg-Signature"]
# if not verify_webhook(request.body, signature, WEBHOOK_SECRET):
#     return 401

Retries

If your endpoint does not return a 2xx response, IdentifyOrg retries the delivery up to 5 times with exponential backoff: 1 second, 5 seconds, 30 seconds, 5 minutes, then 30 minutes. Every attempt is visible in your dashboard's webhook delivery logs, where failed deliveries can also be retried manually.