Skip to main content
This endpoint allows you to subscribe to Dojah’s webhook service. You can also subscribe via the dashboard.
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 below.

​
Request

[POST]
{{baseUrl}}api/v1/webhook/subscribe

​
Headers

  • AppId: Create an app to get your app ID on dashboard here
  • Authorization: Your private secret key

​
Body Parameters

ParameterTypeDescriptionRequired
webhookstringYour callback URL where Dojah will POST events (e.g., https://yourapp.com/webhook)Yes
servicestringType of service to subscribe to (e.g. sms, kyc_widget, address, AML Monitoring)Yes

​
Sample Response

Response
{
 "entity": "Webhook added successfully"
}

​
Response Fields

FieldTypeDescription
entitystringConfirmation message indicating the webhook was added successfully

​
Verification Statuses

These are the possible verification statuses for KYC Widget Webhook Notification Data:
StatusDescription
OngoingThe verification process is currently in progress.
CompletedThe verification process has been successfully completed and passed all steps.
PendingThe verification process is awaiting further action.
FailedThe verification process was not successful.
AbandonedThe verification process was abandoned.

​
Document Types

These are the possible values for document_type in the KYC Widget webhook notification data:
ValueDescription
passportInternational Passport
nationalNational ID
dlDriver’s License
voterVoter’s Card
National Identification Number SlipNIN Slip
All file links (e.g. selfie URLs, ID image URLs, document URLs) returned in webhook notification data 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 Get Verification Details by Reference ID 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

kyc_widget
{
    aml: {
        status: false
    },
    data: {
        id: {
            data: {
                id_url: "https://images.dojah.io/id_sample_id_1720624047.jpg",
                id_data: {
                    extras: "",
                    last_name: "John",
                    first_name: "Doe",
                    mrz_status: "",
                    date_issued: "2019-01-01",
                    expiry_date: "2020-01-01",
                    middle_name: "",
                    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: "John",
                first_name: "Doe"
            },
            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: "John",
                        first_name: "Doe",
                        middle_name: "Anon",
                        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

address verification
{
    "status": "pending",
    "reference_id": "69e10264-4b90-64fe-b4b7-c9dddafd0241",
    "data": {
        "applicant": {
            "first_name": "John",
            "last_name": "Doe",
            "phone": "08012345678",
            "middle_name": "Kabiru",
            "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": ""
    }
}