Webhooks & signatures

Get notified the moment a verification, screening, or message event happens — instead of polling. Dojah POSTs each event to a URL you register, and signs it so you can confirm it’s genuine.

How webhooks work

You subscribe a URL to a service. When a matching event occurs, Dojah sends an HTTP POST with a JSON body to that URL. Respond 200 to acknowledge receipt. Register a callback URL against a service with POST /api/v1/webhook/subscribe. You can also fetch and delete subscriptions.

cURL

curl -X POST "https://api.dojah.io/api/v1/webhook/subscribe" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}" \
  -H "Content-Type: application/json" \
  -d '{ "webhook": "https://yourapp.com/dojah/webhook", "service": "kyc_widget" }'

Documented services include kyc_widget, address, sms, and AML Monitoring, spanning verification, fraud, AML, and messaging events.

Event payload

Events arrive as JSON with the event fields at the top level — unlike REST responses, webhook payloads don’t use the entity wrapper. Always look the event up against your own records using its reference before acting on it.

Verify events are from Dojah

Before trusting a payload, confirm it came from Dojah using any of these:

IP allowlisting

Accept webhook calls only from Dojah’s IP: 135.119.89.106.

Signature with payload (x-dojah-signature)

HMAC SHA256 of the JSON body, signed with your secret key. Recompute and compare.

Signature, secret only (x-dojah-signature-v2)

HMAC SHA256 of just your secret key. Recompute and compare.

Node.js — verify x-dojah-signature

const crypto = require("crypto");

function isFromDojah(req) {
  const expected = crypto
    .createHmac("sha256", process.env.DOJAH_SECRET_KEY)
    .update(JSON.stringify(req.body))
    .digest("hex");
  return expected === req.headers["x-dojah-signature"];
}

Always verify. Treat unverified webhook calls as untrusted — never grant access or update records from a payload you haven’t authenticated.

File links expire. Any file URLs inside a webhook payload are temporary — see File links & expiry.

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Webhooks & signatures

How webhooks work

Event payload

Verify events are from Dojah

​How webhooks work

​Subscribe to a service

​Event payload

​Verify events are from Dojah

How webhooks work

Subscribe to a service

Event payload

Verify events are from Dojah