> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & signatures

> Receive real-time Dojah events, subscribe to services, and verify webhook authenticity with HMAC SHA256 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.

## Subscribe to a service

Register a callback URL against a service with `POST /api/v1/webhook/subscribe`. You can also fetch and delete subscriptions.

```bash cURL theme={null}
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:

<Steps>
  <Step title="IP allowlisting">
    Accept webhook calls only from Dojah’s IP: `135.119.89.106`.
  </Step>

  <Step title="Signature with payload (x-dojah-signature)">
    HMAC SHA256 of the JSON body, signed with your secret key. Recompute and compare.
  </Step>

  <Step title="Signature, secret only (x-dojah-signature-v2)">
    HMAC SHA256 of just your secret key. Recompute and compare.
  </Step>
</Steps>

```js Node.js — verify x-dojah-signature theme={null}
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"];
}
```

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

<Note>
  **File links expire.** Any file URLs inside a webhook payload are temporary — see [File links & expiry](/api-reference/core-concepts/file-links-expiry).
</Note>