What Is a Webhook Event?

A webhook event is a message that one system sends to another the moment something happens. In Dojah's case, the "something" is usually a result: a user finishes an ID verification, an address check completes, or AML monitoring flags a customer. Dojah sends your server a message describing what happened, and your server decides what to do next, such as approving the customer or sending them for review.

Think of waiting for a parcel. You could phone the courier every hour to ask whether it has arrived, or you could give them your number and let them call you when it does. Phoning repeatedly is called polling. A webhook is the courier calling you.

For verification, this matters because results are not instant. A user might take several minutes to upload a selfie, or an address check might need an agent visit. With webhooks, your system does not keep asking Dojah for updates. Dojah tells you when there is one.

This guide explains the concepts first, then walks through four steps: subscribing to events, checking that they really come from Dojah, handling what they contain, and recovering when one goes missing. 

How a Dojah Webhook Event Travels

Here is the full journey of one event:

1. You register a destination: You tell Dojah which URL on your server should receive events, and which type of event you want. This is called subscribing.
2. Something happens: A user completes a verification flow.
3. Dojah sends the event: Dojah sends a message to your URL containing the result.
4. You check it is genuine: Your server confirms the message really came from Dojah.
5. You act on it: Your server reads the result and decides what happens to that customer.

6. You confirm receipt: Your server replies with a 200 response, which tells Dojah the message arrived.

    

The Terms You Will See

Step 1: Subscribe to Webhook Events

Subscribing tells Dojah where to send events and which type you want.

1. Get your credentials: Copy your App ID and secret key from the Dojah dashboard.
2. Send a POST request:Send it to /api/v1/webhook/subscribe with three headers: Authorization (your secret key, with no Bearer prefix), AppId (your App ID) and Content-Type (application/json). The Environments page lists the live and sandbox addresses. 
3. Set the body: Pass two fields. The webhook field is the public HTTPS URL that will receive events, and the service field is one of the services in the table below.
4. Check the response: A 200 response saying the webhook was added means the subscription is live.

Write AML Monitoring exactly as shown, with the space and capital letters. You can subscribe once per service in each environment, so register your endpoint separately for sandbox and live. The subscribe reference has a ready-to-copy example request in cURL, Node.js, and Python, plus the error codes.

Step 2: Verify That Events Are From Dojah

Your endpoint is a public URL, so anyone who finds it could send a fake message claiming a customer passed verification. Dojah's signature lets you tell real events from fake ones. Treat any event you have not verified as untrusted, and never grant access or update a record from one.

1. Allowlist Dojah's IP: Accept webhook calls only from 135.119.89.106.
2. Read the signature header: Every event carries a header called x-dojah-signature.
3. Recompute the signature: Take the raw request body and create an HMAC SHA256 code from it using your webhook secret. This is a standard way of producing a code from a message plus a secret that only you and Dojah know. Find the secret under Developers → Webhooks in the dashboard, in the Secret column. It is not your API secret key, and each subscription has its own.
4. Compare and reject: Compare your code with the header using a constant-time comparison function. If they differ, reject the request with a 401 response and stop.

Hash the raw body exactly as it arrived. Parsing the JSON and writing it out again can change the key order or spacing, which produces a different code.

Every event also carries a second header, x-dojah-signature-v2, which is a SHA256 hash of your secret key on its own. It does not include the payload, so it is useful when your framework hides the raw body. You only need to check one of the two headers.

Dojah's docs have working signature checks in Node.js, Python, PHP, Go, Ruby, and Java. See Webhooks & signatures.

Step 3: Handle the Payload

Once an event is verified, match it to your records and act on its status. Payloads arrive as JSON with the fields at the top level, with no entity wrapper.

1. Match it with the reference ID: Pass a reference_id (at least 10 characters) when you launch the verification flow, and store it. It comes back in the event, so look it up against your own records before acting on it.
2. Read the status: The verification_status field tells you where the session stands. Only Completed, Failed and Abandoned are final. Ongoing and Pending mean another event will follow.

1. Check the result before approving: Completed means finished, not passed. Check the top-level status and the status of each step in data, such as the selfie, address and AML steps. In Dojah's own sample, a session is Completed while the address and AML steps both show false.
2. Ignore late or duplicate events: Your handler should give the same outcome if it receives the same event twice, for example by not approving a customer or sending a welcome email a second time. Once a session reaches a final status, a later event for the same reference ID should not overwrite it.
3. Download files straight away: Selfie, ID and PDF links in the payload expire in about an hour. Copy them to your own storage when the event arrives.

The onboarding payload has three layers: a top-level summary, a data object with one entry per step the user went through, and metadata about the session. The sample payload in the docs shows every field.

Step 4: Handle Failed Deliveries

Servers go down and networks fail, so an event does not always arrive on the first try. Plan for that.

1. Acknowledge quickly: Reply with a 200 response as soon as the event is verified and stored, and do slower work afterwards. Any other response counts as a failed delivery, and Dojah retries failed deliveries automatically.
2. Fall back to a status query: If an event has not arrived for a session you expect to be finished, ask Dojah for the result directly, using the reference ID from the original request. The Get verification endpoint returns the full result, including the status and every check that ran.
3. Check delivery status: The fetch subscriptions endpoint shows the outcome of each subscription's most recent delivery.

Putting It Together

A working Dojah webhook integration comes down to four habits. Subscribe your endpoint to the services you need. Verify every event before you trust it. Read the status and the result of each step before you approve anyone, because Completed only means the session finished. And keep a fallback, so a missed event never costs you a verification result.

Get these right and your system stops asking Dojah whether a verification has finished. Results reach you the moment they exist, and each customer is approved, held for review or turned away on data you have checked.

The webhooks and signatures guide has the signature checks in six languages and a full sample payload, and your sandbox key lets you test your handler with sandbox test data before any live data is involved.

Sign up today and start building with Dojah.