Webhook v3

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

Integration steps

0

Required

1

Required

2

Optional

3

Required

4

Optional

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.

This documentation describes the webhook events sent during the address verification process. There are four main events:

  1. Address Collection

  2. Verification Start

  3. Verification Completion

  4. Verification Cancelled

See example below

const express = require('express');
const app = express();

// Parse JSON requests
app.use(express.json());

// Webhook endpoint
app.post('/webhook', (req, res) => {
    // Immediately acknowledge receipt
    res.status(200).json({ received: true });

    // Process webhook asynchronously
    processWebhook(req.body).catch((error) => {
        console.error('Error processing webhook:', error);
    });
});

// Asynchronous webhook processing
async function processWebhook(webhook) {
    const { event_type, data } = webhook;

    console.log('Processing webhook:', event_type);

    switch (event_type) {
        case 'address.collected':
            await handleAddressCollected(data);
            break;

        case 'address_verification.started':
            await handleVerificationStarted(data);
            break;

        case 'address_verification.completed':
            await handleVerificationCompleted(data);
            break;

        case 'address_verification.cancelled':
            await handleVerificationCancelled(data);
            break;

        default:
            console.log('Unhandled event type:', event_type);
    }
}

// Handler for new addresses
async function handleAddressCollected(data) {
    const { user, location, metadata } = data;
    console.log('New address collected:', {
        userId: metadata.app_user_id,
        locationId: location.id,
        address: location.formatted_address,
    });
}

// Handler for verification start
async function handleVerificationStarted(data) {
    const { address_verification, metadata } = data;
    console.log('Verification started:', {
        userId: metadata.app_user_id,
        verificationId: address_verification.id,
        locationId: address_verification.location_id,
    });
}

// Handler for verification cancelled
async function handleVerificationCancelled(data) {
    const { address_verification, metadata } = data;
    console.log('Verification cancelled:', {
        userId: metadata.app_user_id,
        verificationId: address_verification.id,
        locationId: address_verification.location_id,
    });
}

// Handler for verification completion
async function handleVerificationCompleted(data) {
    const { address_verification, metadata } = data;
    const { status } = address_verification;

    switch (status) {
        case 'verified':
            await updateAddress(
                metadata.app_user_id,
                address_verification.location_id,
                'verified',
            );
            break;

        case 'not_at_address':
            await updateAddress(
                metadata.app_user_id,
                address_verification.location_id,
                'not_at_address',
            );
            break;

        case 'unknown':
            await updateAddress(
                metadata.app_user_id,
                address_verification.location_id,
                'unknown',
            );
            break;
    }

    console.log('Verification completed:', {
        userId: metadata.app_user_id,
        locationId: address_verification.location_id,
        status: status,
    });
}

// Update address status in your system
async function updateAddress(userId, locationId, status) {
    console.log('Updating address status:', {
        userId,
        locationId,
        status,
    });
    // TODO: Add your address update logic here
}

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Webhook server running on port ${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 event parameters here.

curl --location --request POST 'localhost:3000/webhook' \
--header 'Content-Type: application/json' \
--header 'okhi-authorization: N2Y2YzQzOGUtNGRkZS00ZDkzLTllZmItN2JmYmYwMjE3OTI5' \
--data-raw '{
  "event_type": "address.collected",
  "event_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "api_version": "v3",
  "event_timestamp": 1686089970,
  "data": {
    "usage_types": ["digital_verification"],
    "user":  {
      "id": "hbZ69KMuYB",
      "first_name": "Gift",
      "last_name": "Moore",
      "phone": "+2347012345678",
      "email": "gift@okhi.co"
    },
    "metadata": {
      "org_id": "iNjNabYBcK",
      "app_id": "NstCO4hx04",
      "branch_id": "SS3RrryAAT",
      "user_id": "6719380b20f46199b339f504",
      "app_user_id": "x123"
    },
    "location": {
        "ward": "Ikoyi I",
        "formatted_address": "15 Eletu Ogabi Street, Victoria Island, Eti Osa, Lagos, 106104, Nigeria, Directions: Turn left at the red shop",
        "post_code": "106104",
        "street_name": "Eletu Ogabi Street",
        "property_number": "15",
        "neighborhood": "Victoria Island",
        "district": "Eti Osa",
        "lga": "Eti Osa",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "country_code": "ng",
        "geo_point": {
            "lat": 6.4281,
            "lon": 3.4219
        },
        "user_id": "6719380b23f45199b339f504",
        "directions": "Turn left at the red shop",
        "id": "673499e92cc56b50cbac4894",
        "url": "https://okhi.me/673499e92cc93b50cbac4894",
        "plus_code": "6FR5CCHC+6Q",
        "address_line_1": "15 Eletu Ogabi Street, Victoria Island, Eti Osa, Lagos, 106104, Nigeria",
        "usage_types": [
            "digital_verification"
        ]
    }
  }
}'

3. Subscribe to events

To register your webhook listener for events, access OkDash by logging in, select "Settings" and proceed to enter your webhook URL.

4. Validate your webhook using real-time data

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

Webhook signature verification

When a webhook is sent, the payload is signed with a shared webhook signature key using HMAC-SHA256. The signature is included in the request headers. The receiving server may verify this signature before processing the webhook. Get your webhook signature key from OkDash settings page. See a detailed guide on how to implement this here.

Custom header verification

You can verify webhook event notifications that your listener receives when events occur. To verify event notifications, add a custom header to your webhook by adding it on your app configuration on OkDash Settings. 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.

Events

Event Type: address.collected

Description: Triggered when an address is collected from the user, containing comprehensive details about the address, user, and associated metadata.

Fields Overview:

  • event_type: Specifies the event type (always "address.collected" for this event).

  • event_id: Unique identifier for the event instance.

  • api_version: The API version used.

  • event_timestamp: Unix timestamp representing when the event occurred (in seconds).

  • data: Contains the event's main data:

    • usage_types: Types of usage for the location (e.g., ["digital_verification"]).

    • user: Details about the user who provided the location.

    • metadata: Contextual metadata for the event.

    • location: Comprehensive information about the location.

Note: The app_user_id field within the metadata section is your custom app user ID provided during the collection of location data, which is used to uniquely identify users within your application.

Example Payload:

{
  "event_type": "address.collected",
  "event_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "api_version": "v3",
  "event_timestamp": 1686089970,
  "data": {
    "usage_types": ["digital_verification"],
    "user": {
      "id": "hbZ69KMuYB",
      "first_name": "Gift",
      "last_name": "Moore",
      "phone": "+2347012345678",
      "email": "gift@okhi.co"
    },
    "metadata": {
      "org_id": "iNjNabYBcK",
      "app_id": "NstCO4hx04",
      "branch_id": "SS3RrryAAT",
      "user_id": "6719380b20f45199b339f504",
      "app_user_id": "x123",
    },
    "location": {
        "ward": "Ikoyi I",
        "formatted_address": "15 Eletu Ogabi Street, Victoria Island, Eti Osa, Lagos, 106104, Nigeria, Directions: Turn left at the red shop",
        "post_code": "106104",
        "street_name": "Eletu Ogabi Street",
        "property_number": "15",
        "neighborhood": "Victoria Island",
        "district": "Eti Osa",
        "lga": "Eti Osa",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "country_code": "ng",
        "geo_point": {
            "lat": 6.4281,
            "lon": 3.4219
        },
        "user_id": "6719380b20f45199b339f504",
        "directions": "Turn left at the red shop",
        "id": "673499e92cc93b50cbac4894",
        "url": "https://okhi.me/674599e92cc93b50cbac4894",
        "plus_code": "6FR5CCHC+6Q",
        "usage_types": [
            "address_book",
            "digital_verification"
        ]
    }
  }
}

Event Type: address_verification.started

Description: Triggered when the address verification process begins, indicating that verification is underway.

Fields Overview:

  • event_type: Specifies the event type (always "address_verification.started").

  • event_id: Unique identifier for the event instance.

  • api_version: The API version used.

  • event_timestamp: Unix timestamp in milliseconds representing when the event occurred.

  • data: Contains core information for the event.

    • address_verification: Details about the verification, including the status.

    • metadata: Contextual metadata for the event.

Verification Status Options:

  • in_progress: Is always going to be in_progress

Example Payload:

{
  "event_type": "address_verification.started",
  "event_id": "6666bb346c61f7982b4c6119",
  "api_version": "v3",
  "event_timestamp": 1730804353887,
  "data": {
    "address_verification": {
      "id": "668d19f5c3a6b88a1f8e7c2b",
      "status": "in_progress",
      "verification_method": "digital",
      "location_id": "6666bb346c61f7982b4c6119"
    },
    "metadata": {
      "org_id": "FpK1t3QYbx",
      "user_id": "66d034c8c363997f138c63c4",
      "app_user_id": "x123",
      "app_id": "NstCO4hx04",
      "branch_id": "SS3RrryAAT"
    }
  }
}

Event Type: address_verification.completed

Description: Triggered once the address verification process has been completed. This payload provides the final status of the verification.

Fields Overview:

  • event_type: Specifies the event type (always "address_verification.completed").

  • event_id: Unique identifier for the event instance.

  • api_version: The API version used.

  • event_timestamp: Unix timestamp in milliseconds representing when the event occurred.

  • data: Contains core information for the event.

    • address_verification: Provides details of the verification, including the final status.

    • metadata: Contextual metadata for the event.

Verification Status Options:

  • unknown: Verification status could not be determined.

  • not_at_address: User is not at the provided address.

  • verified: Address has been successfully verified.

Example Payload:

{
  "event_type": "address_verification.completed",
  "event_id": "6666bb346c61f7982b4c6119",
  "api_version": "v3",
  "event_timestamp": 1730804353887,
  "data": {
    "address_verification": {
      "id": "668d19f5c3a6b88a1f8e7c2b",
      "status": "verified",
      "status_description": "",
      "verification_method": "digital",
      "location_id": "6666bb346c61f7982b4c6119"
    },
    "metadata": {
      "org_id": "FpK1t3QYbx",
      "user_id": "66d034c8c363997f138c63c4",
      "app_user_id": "x123",
      "app_id": "NstCO4hx04",
      "branch_id": "SS3RrryAAT"
    }
  }
}

Event Type: address_verification.cancelled

Description: Triggered once the address verification process has been cancelled eg. when a user opts out of OkHi. This payload provides the final status of the verification.

Fields Overview:

  • event_type: Specifies the event type (always "address_verification.cancelled").

  • event_id: Unique identifier for the event instance.

  • api_version: The API version used.

  • event_timestamp: Unix timestamp in milliseconds representing when the event occurred.

  • data: Contains core information for the event.

    • address_verification: Provides details of the verification, including the final status.

      • status : will always be cancelled

    • metadata: Contextual metadata for the event.

Example Payload:

{
  "event_type": "address_verification.cancelled",
  "event_id": "6666bb346c61f7982b4c6119",
  "api_version": "v3",
  "event_timestamp": 1730804353887,
  "data": {
    "address_verification": {
      "id": "668d19f5c3a6b88a1f8e7c2b",
      "status": "cancelled",
      "status_description": "",
      "verification_method": "digital",
      "location_id": "6666bb346c61f7982b4c6119"
    },
    "metadata": {
      "org_id": "FpK1t3QYbx",
      "user_id": "66d034c8c363997f138c63c4",
      "app_user_id": "x123",
      "app_id": "NstCO4hx04",
      "branch_id": "SS3RrryAAT"
    }
  }
}
PreviousVerification Status UpdatesNextWebhook Signature Verification Guide

Last updated