# 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_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

```bash
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](/docs/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](https://docs.dojah.io/api-reference/core-concepts/webhooks-signatures) stresses hashing the payload exactly as received, because re-serialised JSON can reorder keys or change spacing.

```javascript
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:

```javascript
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](/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.

### 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](/webhooks/guides/implement-webhook-idempotency).

### 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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) verifies Dojah's signatures and keeps each verification result until your onboarding service has handled it.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Dojah webhooks reliably in minutes.