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-signature header on a Dojah webhook?
  • How do I handle a kyc_widget result and its verification_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'));
}
  • rawBody is the exact bytes received (express.raw({ type: '*/*' }), await request.arrayBuffer(), await request.body()). Never JSON.parse/JSON.stringify before verifying.
  • Compare the whole header value as one digest: no prefix, no list, no timestamp.
  • Python: hmac.compare_digest on bytes (encode both sides; never pass str).
  • Missing, empty or malformed header, or a mismatch: 401. Respond 200 once handled.
  • Dojah also sends x-dojah-signature-v2 (a hash of the secret alone, no payload). Verify only x-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_statusMeaningAction
OngoingUser is still in the flowWait for a terminal event
PendingSubmitted, awaiting a check or manual reviewHold the user; don't grant access
CompletedSession finished (not necessarily passed)Check the top-level status and each step's status in data
FailedVerification could not be completedDon't grant access; let the user retry
AbandonedUser left before finishingPrompt 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →