Agent skill
Dojah Webhooks Skill
Receive and verify Dojah webhooks. Use when setting up a Dojah (KYC, KYB and AML identity verification) webhook endpoint, verifying the x-dojah-signature header, debugging 401s, or handling kyc_widget (EasyOnboard) results with verification_status values such as Completed, Failed and Abandoned.
Install this skill
npx skills add hookdeck/webhook-skills --skill dojah-webhooks
Dojah is an African identity verification, KYC/KYB and AML platform. You subscribe a callback URL to a service (kyc_widget, sms, address or AML Monitoring) and Dojah sends a JSON POST to it when an event happens. For hosted flows (EasyOnboard) the webhook, not the client callback, is the authoritative result.
When to Use This Skill
- How do I receive Dojah webhooks?
- How do I verify the
x-dojah-signatureheader on a Dojah webhook? - How do I handle a
kyc_widgetresult and itsverification_status? - Why does my Dojah webhook signature verification fail or return 401?
- Which secret signs Dojah webhooks: the API secret key or the webhook secret?
Setup note
Paste the webhook secret from Developers > Webhooks, not your API secret key.
Store it as DOJAH_WEBHOOK_SECRET. Each subscription has its own secret (the Secret column on Developers → Webhooks in the Dojah dashboard).
Verification (core)
Dojah sends x-dojah-signature: the bare lowercase hex HMAC-SHA256 of the raw request body, keyed with the webhook secret (UTF-8 bytes, used as-is). Nothing else is signed.
const crypto = require('crypto');
function verifyDojahSignature(rawBody, signatureHeader, secret) {
if (!secret || typeof signatureHeader !== 'string') return false;
// Validate before decoding: Buffer.from(x, 'hex') silently drops bad characters
if (!/^[0-9a-f]{64}$/i.test(signatureHeader)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
return crypto.timingSafeEqual(expected, Buffer.from(signatureHeader, 'hex'));
}
rawBodyis the exact bytes received (express.raw({ type: '*/*' }),await request.arrayBuffer(),await request.body()). NeverJSON.parse/JSON.stringifybefore verifying.- Compare the whole header value as one digest: no prefix, no list, no timestamp.
- Python:
hmac.compare_digeston bytes (encode both sides; never passstr). - Missing, empty or malformed header, or a mismatch:
401. Respond200once handled. - Dojah also sends
x-dojah-signature-v2(a hash of the secret alone, no payload). Verify onlyx-dojah-signature. - No timestamp is signed, so there is no replay window to check. Make handlers idempotent (key on
reference_id).
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Events
Dojah has no event-name field or header: the URL is subscribed to one service, and the body is the event at the top level (no entity wrapper). For kyc_widget, dispatch on verification_status:
verification_status | Meaning | Action |
|---|---|---|
Ongoing | User is still in the flow | Wait for a terminal event |
Pending | Submitted, awaiting a check or manual review | Hold the user; don't grant access |
Completed | Session finished (not necessarily passed) | Check the top-level status and each step's status in data |
Failed | Verification could not be completed | Don't grant access; let the user retry |
Abandoned | User left before finishing | Prompt them to resume |
Match the event to your user with reference_id, and treat every field as untrusted until you have checked its type. File URLs in the payload expire in about an hour: download them promptly.
Environment Variables
DOJAH_WEBHOOK_SECRET=your_webhook_secret # Developers > Webhooks > Secret, not the API secret key
Local Development
Dojah can't reach localhost. Tunnel with the Hookdeck CLI (no account required):
npx hookdeck-cli listen 3000 dojah --path /webhooks/dojah
Use the printed URL as the webhook URL when you subscribe. In Hookdeck, create a source of type Dojah: Hookdeck's source verifies the signature using the same webhook secret.
Resources
- references/overview.md - What Dojah webhooks are, services, payload and statuses
- references/setup.md - Subscribe a URL and find the webhook secret
- references/verification.md - Signature details, gotchas, debugging 401s
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests