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

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dojah-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dojah-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dojah-webhooks/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

```bash
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):

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/dojah-webhooks/references/overview.md) - What Dojah webhooks are, services, payload and statuses
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/dojah-webhooks/references/setup.md) - Subscribe a URL and find the webhook secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/dojah-webhooks/references/verification.md) - Signature details, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/dojah-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests