Guide to Dojah Webhooks: Features and Best Practices
Dojah verifies identities for businesses in Africa: government ID lookups, document and selfie checks, address verification and AML screening, often through its hosted EasyOnboard widget. A verification can take minutes or need manual review, and the user may close the browser before it finishes. Dojah's webhooks deliver the result to your server whenever it is ready, and Dojah treats that webhook, not the widget's browser callback, as the authoritative outcome.
This guide explains Dojah's per-service subscriptions, how to read a KYC widget result without mistaking "completed" for "approved", which of Dojah's two signature headers to trust, and what Dojah leaves undocumented about delivery.
What are Dojah webhooks?
You subscribe a URL to a service, separately for the Live and Sandbox environments. When something happens in that service, Dojah sends a JSON POST to the URL. There is one subscription per service per environment.
| Service | Delivers |
|---|---|
kyc_widget | Result of a hosted flow (EasyOnboard) session |
sms | SMS delivery events |
address | Address verification events |
AML Monitoring | AML monitoring hits |
The body doesn't say which service sent it, and there is no event name. Because each service has its own subscription, the URL is the practical way to tell them apart.
Each subscription has its own webhook secret, and Dojah signs every delivery with it in x-dojah-signature. Dojah also sends a second header and publishes a source IP, which this guide covers below.
Dojah webhook features
| Feature | Details |
|---|---|
| Subscription | Developers > Webhooks or POST /api/v1/webhook/subscribe |
| Scope | One URL per service per environment (Live or Sandbox) |
| Signature | hex HMAC-SHA256 |
| Signature header | x-dojah-signature |
| Signed content | The raw request body |
| Secret | Per subscription, from the Secret column, not the API secret key |
| Second header | x-dojah-signature-v2, a SHA256 of the API secret key only |
| Source IP | 135.119.89.106 |
| Body | JSON, with no entity wrapper and no event field |
| Response | 200 to acknowledge |
| Retries and timeout | Not documented |
Events and payloads
Dojah has no event-name field or header. The URL is subscribed to one service, so dispatch on the body. For kyc_widget, the field to read is verification_status:
verification_status | Triggered When | Common Use Cases |
|---|---|---|
Ongoing | The user started the flow and is still working through it | Nothing yet |
Pending | Every step was submitted; outcome awaits a check or manual review | Hold the user in review |
Completed | The session finished and a result is available | Inspect status and each step before deciding |
Failed | The verification could not be completed | Let the user retry |
Abandoned | The user left the flow before finishing | Prompt the user to resume |
Only Completed, Failed and Abandoned are terminal. Completed means finished, not passed: check the top-level status and each step's status inside data (a session can be Completed while address.status or aml.status is false).
A KYC widget body has three layers:
- Top level: the summary, including
reference_id,verification_status,status, the ID type and number captured,verification_typeandverification_mode(the kind of check, such asDL_IDandLIVENESS), and links to the selfie, ID images and a verification PDF. data: one key per step in the flow, such asuser_data,id,selfieandaddress, each with its ownstatus,messageanddata. Some entries, such asadditional_document, have nostatus. Anamlobject with its ownstatussits at the top level.metadata: session context, such as geo-IP details and anything you passed when launching the widget.
reference_id is the value you supplied when launching the flow, so it is how you find the user. File URLs are pre-signed and expire in about an hour, so download anything you need to keep straight away. Dojah documents only the kyc_widget body. The sms, address and AML Monitoring payloads have their own shapes and no published example.
Setting up Dojah webhooks
Paste the webhook secret from Developers > Webhooks, not your API secret key.
Subscribe in the dashboard
- Open Developers > Webhooks and select Subscribe.
- Choose the app, enter your Webhook URL, and pick the service, for example KYC Widget.
- Find the new subscription in the list and reveal its Secret with the eye icon. Store it as, for example,
DOJAH_WEBHOOK_SECRET.
The list shows each subscription's Environment. Subscribe again for Sandbox or Live as needed, and keep each secret with the matching environment.
Subscribe with the API
curl -X POST "https://api.dojah.io/api/v1/webhook/subscribe" \
-H "Authorization: $DOJAH_SECRET_KEY" \
-H "AppId: $DOJAH_APP_ID" \
-H "Content-Type: application/json" \
-d '{ "webhook": "https://yourapp.com/webhooks/dojah", "service": "kyc_widget" }'
Authorization is your app's secret key sent as-is, without Bearer. service is one of kyc_widget, sms, address or AML Monitoring. Dojah also has endpoints to fetch and delete subscriptions. The URL must be public HTTPS.
With Hookdeck
Create a source with the Dojah source type and paste the subscription's webhook secret into its verification settings, then subscribe the Hookdeck source URL. Use one source per service and environment, since each subscription has its own secret. The Hookdeck CLI can forward Sandbox deliveries to a local server: npx hookdeck-cli listen 3000 dojah --path /webhooks/dojah.
Securing Dojah webhooks
Compute an HMAC-SHA256 of the raw body with the subscription's webhook secret, encode it as hex, and compare it with x-dojah-signature in constant time. Dojah's signature page stresses hashing the payload exactly as received, because re-serialised JSON can reorder keys or change spacing.
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-dojah-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
A KYC widget receiver acts only on terminal statuses, and checks every step before approving anyone:
const express = require('express');
const app = express();
app.post('/webhooks/dojah/kyc', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.DOJAH_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let result;
try {
result = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!result || typeof result !== 'object' || Array.isArray(result)) return res.sendStatus(400);
try {
const steps = result.data && typeof result.data === 'object' ? Object.values(result.data) : [];
const checked = steps.filter((step) => step && typeof step === 'object' && 'status' in step);
if (result.verification_status === 'Completed') {
const amlClear = !result.aml || result.aml.status !== false;
const passed = result.status === true && amlClear && checked.every((step) => step.status === true);
await recordKycDecision(result.reference_id, passed ? 'approved' : 'needs_review');
} else if (['Failed', 'Abandoned'].includes(result.verification_status)) {
await recordKycDecision(result.reference_id, result.verification_status.toLowerCase());
}
// Ongoing and Pending: another delivery will follow.
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
recordKycDecision is your own code. The check skips data entries without a status and treats a top-level aml.status of false as a failure. Mount a separate route, with its own secret, for each other service you subscribe to.
Ignore x-dojah-signature-v2 for verification. It is a SHA256 hash of your API secret key alone, so it is the same on every request, says nothing about the body, and works for anyone who has seen one delivery. The source IP 135.119.89.106 is a reasonable extra check at the network edge of your own infrastructure, but not a replacement for the HMAC.
Nothing time-based is signed, so verified requests can be replayed. Hookdeck's Dojah source verifies x-dojah-signature only, with no timestamp window. It returns 200 to Dojah and marks a request that fails the check as failed verification, instead of a 401.
Make Dojah webhooks production-ready. Hookdeck Event Gateway verifies
x-dojah-signatureon every KYC, SMS, address and AML delivery, stores each result, and retries delivery to your onboarding service until it succeeds.
Dojah webhook limitations and pain points
Two secrets that look interchangeable
The Problem: Verification never matches, even though you are using a secret from the Dojah dashboard.
Why It Happens: The API secret key and the webhook secret both live in the dashboard. Only the per-subscription webhook secret signs x-dojah-signature, and Live and Sandbox subscriptions have different ones.
Workarounds:
- Copy the secret from the Secret column of the specific subscription.
- Name stored secrets by service and environment, such as
DOJAH_.KYC_ LIVE_ WEBHOOK_ SECRET
How Hookdeck Can Help: Hookdeck's Dojah source tells you which secret to paste, and keeping one source per subscription means each secret lives in exactly one place.
"Completed" is not "approved"
The Problem: Users who failed a check are let through.
Why It Happens: verification_ only means the session ended. The pass or fail result is in status and in each step's status, and a completed session can include a failed address or AML step.
Workarounds:
- Require
statusand every step'sstatusto be true before approving. - Send anything else to manual review.
How Hookdeck Can Help: Hookdeck filters can route Completed sessions to your decision service and drop Ongoing updates, while keeping every payload in the request log for audit.
Undocumented retries
The Problem: A KYC result that hit a failing endpoint may be gone.
Why It Happens: Dojah says to respond 200 but documents no retry policy or timeout.
Workarounds:
- Keep the endpoint available and respond quickly.
- For users stuck in review, look up the verification through Dojah's API or dashboard.
How Hookdeck Can Help: Hookdeck accepts each result on Dojah's first attempt, stores it, and retries your service on a schedule you set.
Expiring file links
The Problem: Selfie and ID image links stop working when you open them later.
Why It Happens: The URLs in the payload are pre-signed and expire in about an hour.
Workarounds:
- Download the files you need to keep as soon as the webhook is processed.
How Hookdeck Can Help: Hookdeck delivers the result to your service as soon as it can and retries quickly after a failure, which leaves more of the hour for your downloads.
Best practices
Trust the webhook, not the browser
The widget's onSuccess, onError and onClose callbacks run in the user's browser and can be faked. Grant access only after a verified webhook confirms the result.
Route by URL
Give each service its own path or Hookdeck source, because the body never names the service.
Use reference_id as your key
You choose reference_id when launching the widget, so make it something you can look up, such as your user ID. Combine it with verification_status to deduplicate. More patterns are in handling duplicate webhooks.
Keep personal data out of logs
Payloads include ID numbers, faces and addresses. Log the reference_id and status, and store the rest under the same controls as the rest of your KYC data. Process the result after responding, as described in why to process webhooks asynchronously.
Conclusion
Dojah's webhooks deliver identity verification results per service, with the KYC widget result as the authoritative outcome of a hosted flow. Verify x-dojah-signature with the subscription's own secret, ignore the static v2 header, route by URL, and approve a user only when every step passed, not just when the session completed.
Hookdeck Event Gateway verifies Dojah's signatures and keeps each verification result until your onboarding service has handled it.
Get started with Hookdeck for free and handle Dojah webhooks reliably in minutes.