Gareth Wilson Gareth Wilson

Guide to Dojah Webhooks: Features and Best Practices

Published


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.

ServiceDelivers
kyc_widgetResult of a hosted flow (EasyOnboard) session
smsSMS delivery events
addressAddress verification events
AML MonitoringAML 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

FeatureDetails
SubscriptionDevelopers > Webhooks or POST /api/v1/webhook/subscribe
ScopeOne URL per service per environment (Live or Sandbox)
Signaturehex HMAC-SHA256
Signature headerx-dojah-signature
Signed contentThe raw request body
SecretPer subscription, from the Secret column, not the API secret key
Second headerx-dojah-signature-v2, a SHA256 of the API secret key only
Source IP135.119.89.106
BodyJSON, with no entity wrapper and no event field
Response200 to acknowledge
Retries and timeoutNot 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_statusTriggered WhenCommon Use Cases
OngoingThe user started the flow and is still working through itNothing yet
PendingEvery step was submitted; outcome awaits a check or manual reviewHold the user in review
CompletedThe session finished and a result is availableInspect status and each step before deciding
FailedThe verification could not be completedLet the user retry
AbandonedThe user left the flow before finishingPrompt 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_type and verification_mode (the kind of check, such as DL_ID and LIVENESS), and links to the selfie, ID images and a verification PDF.
  • data: one key per step in the flow, such as user_data, id, selfie and address, each with its own status, message and data. Some entries, such as additional_document, have no status. An aml object with its own status sits 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

  1. Open Developers > Webhooks and select Subscribe.
  2. Choose the app, enter your Webhook URL, and pick the service, for example KYC Widget.
  3. 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-signature on 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_status: Completed 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 status and every step's status to 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.

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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.