> ## 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.
# Subscribe to Webhooks
> Register a URL to receive KYC, OTP, AML, and wallet events in real time. One subscription per URL and event type.
This endpoint allows you to subscribe to Dojah's webhook service. You can also subscribe via the [dashboard](/dashboard-guide/integrations/developers/webhooks).
**Webhook responses do not use the `entity` wrapper.** Unlike Dojah API responses — which wrap data inside an `"entity": { ... }` object — webhook notification payloads deliver data directly at the top level. See [Sample Webhook Notifications](#sample-webhook-notifications) below.
### Request
```http [POST] theme={null}
{{baseUrl}}api/v1/webhook/subscribe
```
### Headers
* `AppId`: Create an app to get your app ID on dashboard [here](https://app.dojah.io/developers/configuration)
* `Authorization`: Your private secret key
### Body Parameters
| Parameter | Type | Description | Required |
| --------- | ------ | --------------------------------------------------------------------------------------- | -------- |
| `webhook` | string | Your callback URL where Dojah will POST events (e.g., `https://yourapp.com/webhook`) | Yes |
| `service` | string | Type of service to subscribe to (e.g. `sms`, `kyc_widget`, `address`, `AML Monitoring`) | Yes |
### Sample Response
```json Response theme={null}
{
"entity": "Webhook added successfully"
}
```
### Response Fields
| Field | Type | Description |
| ------ | ------ | ------------------------------------------------------------------ |
| entity | string | Confirmation message indicating the webhook was added successfully |
### Verification Statuses
These are the possible verification statuses for KYC Widget Webhook Notification Data:
| Status | Description |
| --------- | ------------------------------------------------------------------------------ |
| Ongoing | The verification process is currently in progress. |
| Completed | The verification process has been successfully completed and passed all steps. |
| Pending | The verification process is awaiting further action. |
| Failed | The verification process was not successful. |
| Abandoned | The verification process was abandoned. |
### Document Types
These are the possible values for `document_type` in the KYC Widget webhook notification data:
| Value | Description |
| ------------------------------------- | ---------------------- |
| `passport` | International Passport |
| `national` | National ID |
| `dl` | Driver's License |
| `voter` | Voter's Card |
| `National Identification Number Slip` | NIN Slip |
All file links (e.g. selfie URLs, document URLs) returned in the response expire within **one hour**. We strongly recommend transferring these documents and images to your own infrastructure as soon as you receive them. If a link expires before you are able to download the file, call the [Fetch KYC widget Verification Data](/docs/technical-reference/get-verification-details) or [Fetch Address Verification Data](/docs/address-verification/fetch-address-verification-data) endpoint to generate a new link — which will also expire in one hour.
### Sample Webhook Notifications
**Webhook responses do not use the `entity` wrapper.** Unlike Dojah API responses — which wrap data inside an `"entity": { ... }` object — webhook notification payloads deliver data directly at the top level. Do not expect the `entity`, `error`, or `status` envelope when handling webhooks.
#### KYC Widget notification
```json kyc_widget theme={null}
{
aml: {
status: false
},
data: {
id: {
data: {
id_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
id_data: {
extras: "",
last_name: "Musa",
first_name: "John",
mrz_status: "",
date_issued: "2019-01-01",
expiry_date: "2020-01-01",
middle_name: "Doe",
nationality: "Nigerian",
date_of_birth: "1990-01-01",
document_type: "National ID",
document_number: "123456789"
},
back_url: "https://images.dojah.io/id_sample_id_1720624047.jpg"
},
status: true,
message: "Successfully verified your id"
},
email: {
data: {
email: "abc@gmail.com"
},
status: true,
message: "abc@gmail.com validation Successful"
},
index: {
data: {},
status: true,
message: "Successfully continued to the main checks."
},
selfie: {
data: {
selfie_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg"
},
status: true,
message: "Successfully validated your liveness"
},
countries: {
data: {
country: "Nigeria"
},
status: true,
message: "Successfully continued to the next step."
},
user_data: {
data: {
dob: "1990-12-03",
last_name: "Musa",
first_name: "John"
},
status: true,
message: ""
},
business_id: {
image_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg",
business_name: "ABC Company LIMITED",
business_type: "Business",
business_number: "1237654",
business_address: "",
registration_date: ""
},
phone_number: {
data: {
phone: "234810123456"
},
status: true,
message: "2348103817187 validation Successful"
},
business_data: {
business_name: null,
business_type: "BN",
business_number: null,
business_address: null,
registration_date: null
},
government_data: {
data: {
bvn: {
entity: {
bvn: "222222222222",
nin: "",
email: "",
title: "",
gender: "Male",
customer: "6bb82c41-e15e-4308-b99d-e9640818eca9",
image_url: "https://images.dojah.io/id_John_Doe_1720615487.jpg",
last_name: "Musa",
first_name: "John",
middle_name: "Doe",
nationality: "",
name_on_card: "",
watch_listed: "",
date_of_birth: "01-Jun-1982",
lga_of_origin: "",
phone_number1: "08011111111",
phone_number2: "",
marital_status: "",
enrollment_bank: "",
state_of_origin: "",
level_of_account: "",
lga_of_residence: "",
enrollment_branch: "",
registration_date: "",
state_of_residence: "",
residential_address: ""
}
},
nin: {
entity: {
nin: "1234567891",
firstname: "John",
middlename: "Doe",
surname: "Anon",
maidenname: "",
telephoneno: "0901234567",
state: "",
place: "",
profession: "ZOOLOGY",
title: "",
height: "167",
email: "",
birthdate: "1960-01-01",
birthstate: "",
birthcountry: "Not Available",
centralID: "",
documentno: "",
educationallevel: "tertiary",
employmentstatus: "unemployed",
othername: "",
pfirstname: "",
pmiddlename: "",
psurname: "",
nspokenlang: "YORUBA",
ospokenlang: "",
religion: "christianity",
residence_Town: "",
residence_lga: "Alimosho",
residence_state: "Lagos",
residencestatus: "birth",
residence_AddressLine1: "No 2 Anon house, John does estate, Lagos state, Nigeria",
residence_AddressLine2: "",
self_origin_lga: "",
self_origin_place: "",
self_origin_state: "",
signature: null,
nationality: null,
gender: "Female",
trackingId: "",
customer: "1234444y373737373737373737",
image_url: "https://images.dojah.io/id_SANDBOX_1721830110.jpg"
}
}
},
status: true,
message: ""
},
additional_document: [
{
document_url: "https://dojah-image.s3.amazonaws.com/66bcc73a4ff8e1003100454212aec768-3344-4df5-88f6-7e723c46cbb0.jpeg",
document_type: "image"
}
]
},
value: "123456",
id_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
status: true,
id_type: "BVN",
message: "Successfully completed the verification.",
back_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
metadata: {
ipinfo: {
as: "AS29465 MTN NIGERIA Communication limited",
isp: "MTN NIGERIA Communication limited",
lat: 6.4474,
lon: 3.3903,
org: "MTN Nigeria",
zip: "",
city: "Lagos",
proxy: false,
query: "102.89.34.49",
mobile: true,
status: "success",
country: "Nigeria",
hosting: true,
district: "",
timezone: "Africa/Lagos",
region_name: "Lagos"
},
device_info: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
},
selfie_url: "https://images.dojah.io/selfie_sample_image_1720624219.jpg",
reference_id: "DJ-31038041E0",
verification_url: "https://app.dojah.io/verifications/bio-data/49fd74a4-8181-4ce8-a87a-0e63f7159257",
verification_mode: "LIVENESS",
verification_type: "RC-NUMBER",
verification_value: "123456",
verification_status: "Completed"
}
```
#### Address verification notification
```json address verification theme={null}
{
"status": "pending",
"reference_id": "69e10264-4b90-64fe-b4b7-c9dddafd0241",
"data": {
"applicant": {
"first_name": "John",
"last_name": "Musa",
"phone": "08012345678",
"middle_name": "Doe",
"photo": "",
"gender": "Male",
"dob": "17/01/1988"
},
"location": "7.081273, 8.232523",
"photos": [
""
],
"neighbor": {
"name": "Musa Garba",
"comment": "Very friendly",
"phone": "080987654321"
},
"city": "oshodi",
"street": "270 Murtala Muhammed Way, Alagomeji. Yaba",
"lga": "lagos mainland",
"state": "Lagos",
"country": "Nigeria",
"comments": ""
}
}
```