Webhook

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

Integration steps

#	Required	Step
0	Required	Integrate OkHi's mobile libraries
1	Required	Configure a webhook listener
2	Optional	Test your webhook
3	Required	Subscribe to events
4	Optional	Validate your listener configurations with mock webhook events

1. 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

Illustration of the various verification statuses and modes across different verification windows

See example below

NodeJS with Express

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}`);
});

Webhook timeouts

Webhook timeouts When OkHi sends an event to a webhook endpoint, the service must respond within 15 seconds. If OkHi does not receive a response within that period, the system logs a timeout error and retries the event later.

Destination endpoint APIs have fluctuations in availability due to a number of issues ranging from network failures to overload to bugs. OkHi’s internal systems retry failed destination API calls for few minutes with an exponential backoff after each attempt. This substantially improves delivery rates.

Take note that, in the event of a timeout error, where the destination API endpoint does process the event beyond the set time out window. When OkHi retries the event later, the destination API endpoint will end up with a duplicate event.

2. 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.

Verification started

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"
    }
}'

Verified

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"
    }
}'

Not at address

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"
    }
}'

Unknown

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.

3. Subscribe to events

To register your webhook listener for events, access OkDash by logging in and then click on the profile icon located at the top-right corner. After that, select "settings" and proceed to enter your webhook URL.

4. Validate your webhook using real-time data

Use the verification status simulator API for this.

After successfully subscribing your webhook listener to events, put it to the test by creating a new address and initiating verification. Your webhook will then receive notifications as intended and demonstrate its expected functionality.

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

Name	Type	Description
v2.address_verification_id	String	Every address verification request will generate a unique alphanumeric identifier. Unique to the verification window + address ID
v2.verification_status	String	Review address verification status in FAQ
v2.verification_mode	String	Value is either going to be: first_time: if the verification just got initiated and in the first 7 days window. continuous: the first window is complete, and the user is in the second or subsequent verification windows
v2.user_id	String	OkHi user ID unique to the user
v2.location_id	String	OkHi address ID unique to the address

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.