Signed eventsRetry enabled

Webhooks Overview

Production-grade webhook documentation for signed event delivery, retries, failed deliveries, event logs, and compliance-safe integrations.

What are webhooks?

Webhooks allow Xaqiiji to notify your application in real time when important events happen, such as completed verifications, failed verification attempts, low credit balance, and account status changes.

Why use webhooks?

Use cases

Update customer verification status after POST /verify/citizen

Trigger HR onboarding when verification_completed fires

Alert finance when credits_low or credits_exhausted fires

Pause integrations when business_suspended fires

Sync verification results into ERP/CRM systems

Webhook flow diagram

Xaqiiji EventSigned Webhook PayloadYour HTTPS Endpoint2xx ResponseEvent Marked Delivered

Configure in the business portal

POST/business/enterprise/developer/webhooks

Add webhook URL

PATCH/business/enterprise/developer/webhooks

Update webhook URL or events

Change the destination URL or subscribed events from the portal.

DELETE/business/enterprise/developer/webhooks

Remove webhook endpoint

Deactivate or remove a webhook configuration from the portal.

Webhook URLs and event subscriptions are managed in the business portal under Developer → Webhooks. There is no public REST API for webhook management today.

Example portal payload

request

{  "url": "https://api.example.com/xaqiiji/webhooks",  "events": [    "verification_completed",    "verification_failed",    "credits_low"  ],  "isActive": true}

application/json

{  "message": "Webhook endpoint saved",  "data": {    "id": "uuid",    "url": "https://api.example.com/xaqiiji/webhooks",    "events": ["verification_completed", "verification_failed", "credits_low"],    "isActive": true  }}

Security summary

Security checklist

Use HTTPS endpoints only

Verify x-xaqiiji-signature before processing

Reject timestamps outside a 5-minute window

Store WEBHOOK_SIGNING_SECRET securely

Treat events as idempotent using event + delivery ID

Do not trust unsigned payloads

Next steps

Add a sandbox webhook URL in the portal, verify signatures using the examples below, confirm your endpoint returns 2xx, then monitor delivery attempts in the portal.

Event Types

Edit this page

Was this page helpful?