Webhook

Use a webhook to keep track of changes in verification statuses of your user's addresses.

Integration steps

Configure a webhook listener

A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when a status change event occurs.

Below is an illustration of the possible verification statuses and modes across different verification windows

See example below

import express, { Request, Response } from "express";
// This example uses Express to receive webhooks
const app = express();
const port = 3000;
app.use(express.json());
app.post('/webhook', (request, response) => {
    // Retrieve the request's body
    // Validate custom headers
    const profile = request.body.v2;
    const status = profile?.verification_status;
    const mode = profile?.verification_mode;
    if (!status && !mode) {
        // stop
        return response.sendStatus(200);
    }

    // Do something with event
    switch (status) {
        case 'verified':
            // Define and call a method to handle the successful verification status
            // handleVerificationSuccessful()
            console.log('handleVerificationSuccessful()');
            break;
        case 'not_at_address':
            // Define and call a method to handle the `not at address` status
            // handleVerificationFailed(status)
            console.log(`handleVerificationFailed(${status})`);
            break;
        case 'unknown':
            // Define and call a method to handle the `unknown` status
            // handleVerificationFailed(status)
            console.log(`handleVerificationFailed(${status})`);
            break;
        default:
            if (mode === 'first_time' && typeof status === 'undefined') {
                // Define and call a method to handle the verification in progress status
                // handleVerificationInProgress()
                console.log('handleVerificationInProgress()');
            } else {
                console.log(`Unhandled event type ${status}`);
            }
    }
    response.sendStatus(200);
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

Test your webhook (optional)

Once you have configured your webhook, test it by making a POST request to your webhook similar to the example below. See description of the JSON body parameters here.

curl --location --request POST 'localhost:3000/webhook' \
--header 'Content-Type: application/json' \
--header 'okhi-authorization: N2Y2YzQzOGUtNGRkZS00ZDkzLTllZmItN2JmYmYwMjE3OTI5' \
--data-raw '{
    "v2": {
        "branch_id": "4jwj356hIm",
        "location_id": "uauCHxNJBs",
        "user_id": "hbZ69KMuYB",
        "address_verification_id": "UmZx9kxyvj",
        "status_description": "",
        "payload_version": "v2.0",
        "verification_mode": "first_time"
    }
}'

curl --location --request POST 'localhost:3000/webhook' \
--header 'Content-Type: application/json' \
--header 'okhi-authorization: N2Y2YzQzOGUtNGRkZS00ZDkzLTllZmItN2JmYmYwMjE3OTI5' \
--data-raw '{
    "v2": {
        "branch_id": "4jwj356hIm",
        "location_id": "jeSk9f54Ug",
        "user_id": "hbZ69KMuYB",
        "address_verification_id": "cn7V6ddO3w",
        "status_description": "",
        "payload_version": "v2.0",
        "verification_status": "verified",
        "verification_mode": "continuous"
    }
}'

curl --location --request POST 'localhost:3000/webhook' \
--header 'Content-Type: application/json' \
--header 'okhi-authorization: N2Y2YzQzOGUtNGRkZS00ZDkzLTllZmItN2JmYmYwMjE3OTI5' \
--data-raw '{
    "v2": {
        "branch_id": "4jwj356hIm",
        "location_id": "jeSk9f54Ug",
        "user_id": "hbZ69KMuYB",
        "address_verification_id": "PCNNrkWgDI",
        "status_description": "",
        "payload_version": "v2.0",
        "verification_status": "not_at_address",
        "verification_mode": "continuous"
    }
}'

curl --location --request POST 'localhost:3000/webhook' \
--header 'Content-Type: application/json' \
--header 'okhi-authorization: N2Y2YzQzOGUtNGRkZS00ZDkzLTllZmItN2JmYmYwMjE3OTI5' \
--data-raw '{
    "v2": {
        "branch_id": "4jwj356hIm",
        "location_id": "HMBfeVuSA3",
        "user_id": "hbZ69KMuYB",
        "address_verification_id": "xBDTUdl6g2",
        "status_description": "",
        "payload_version": "v2.0",
        "verification_status": "unknown",
        "verification_mode": "first_time"
    }
}'

Deprecation notice:

There will be some extra data, that is not documented above, in the payload that is sent to your webhook. Do not add logic that relies on the extra data that is not documented here as the extra fields will be deprecated soon.

Next, subscribe your listener to events.

To subscribe your webhook listener to events, fill out this form

Simulate verification status change (Optional)

Prerequisite

You will require a valid location ID, this is part of the payload returned by OkCollect after successfully creating an OkHi address.

Mock verification

Once you have subscribed your webhook listener to events, you may simulate verification status changes to ensure that your webhook receives notifications and behaves as expected.

Use the verification status simulator API for this.

Congratulations!

You have a basic webhook endpoint ready to accept verification events from OkHi. Now add the application logic that your business needs to handle the events you care the most about. You can also extend the endpoint with the steps below to verify the authenticity of the requests.

Secure your webhook

You can verify webhook event notifications that your listener receives when events occur. To verify event notifications, add a custom header to your webhook. We will then send the custom header along with each webhook event and you can validate the events based on correctness of the custom header.

JSON Body Parameters