OkCollect Webhook

This webhook allows log user interactions with their OkHi address enabling you to get rich data insights from OkHi.

Create an address interaction

POST https://sandbox-server.okhi.dev/v5/interactions

Headers

NameTypeDescription

api-key

string

Your Server API key to track your app's interactions

Request Body

NameTypeDescription

user

string

OkHi user object, see example below

value

number

eg. for a checkout this could be the order amount

id

string

A unique order ID

useCase

string

for loans this could be "loan". For e-commerce this could be: "e-commerce"

locationId

string

OkHi location ID

location

object

OkHi location object would be required if you don't have a location ID. See example below

properties

object

This is an open field where you can put any business related information related to the interaction for use in analysis later. See an example below.

{
    "success": true
}

If you don't supply a locationId then the user & location parameters are required

Properties Object

A dictionary of information that provides useful details to a given address interaction relevant to your business.

All fields except the ones listed in the table below are open to you to design to suit your business.

Field

Type

Description

sendToQueue

boolean

Mostly used in e-commerce. Set to true in order to push the checkout details to OkHi Queue app for dispatch management

paymentMethod

string

Mode of payment used in a checkout context

dates

date

All dates should be in ISO 8601 format

brand

string

Your brand name in one word, all lowercase eg acme

location

string

The outlet location in one word, all lowercase eg. thehub

value

float

A numeric value associated with the interaction, eg. total basket value

currency

string

Currency code in ISO 4217 format

Here's an example of a properties JSON object that you could have in a checkout context:

Properties Object
{
  "brand": "acme",
  "branch": "thehub",
  "paymentMethod": "cash",
  "currency": "KES",
  "sendToQueue": true,
  "basket": [
    {
      "sku": "RF67DESL1/XFA",
      "value": 180000.00,
      "name": "RF67DESL FDR with Twin Cooling Plus, 491 L",
      "description": "Refrigerator is designed to improve the way you store food through an innovative 2-Door system.",
  	  "category" : "fridge",
      "quantity": 1
    },
    {
      "sku": "MG28J5255GS/SM",
      "value": 5500.00,
      "name": "MW5200J Grill Microwave Oven with Healthy Steam, 28 L",
      "description": "Enjoy the flexibility to bake and microwave – all from one appliance",
      "category": "microwave ovens",
      "quantity": 1,
      "weight": 1.2
    }
  ],
  "shipping": {
    "cost": 120.00,
    "class": "Flat rate",
    "expectedDeliveryDate": "2019-08-12T09:42:22.526Z"
  }
}

User Object

This is only required if you don't have an OkHi location ID

OkHi User object
{
    "firstName": "Gift",
    "lastName": "Moore",
    "phone": "+234xxxx" // It is important to provide your actual phone number, as a message will be sent to this number
}

Location Object

This is only required if you do not have an OkHi location Id.

You must supply at least one of these fields: a street name, property name, directions, placeId(from OkHi), lat & lng

Field

Type

Description

propertyName

string

Building name eg. Riverside Villas

propertyNumber

string

Building number eg 12

streetName

string

Street name eg. Peponi Road

lat

float

Latitude eg. -1.21231

lng

float

Longitude eg. 35.123123

placeId

string

OkHi place ID that refers to a unique common address in our database

directions

string

Take a left where the goats used to graze

otherInformation

string

Useful instructions of how get to the door eg. Call the askari on 072112...

businessName

string

Business name eg. ACME LTD

unit

string

Unit identifier eg. APT 12A

floor

string

Floor number

An example of an OkHi location JSON object, only required if you don't have a location ID

OkHi Location Object
{
        "lat": -1.2489607,
        "lng": 36.7521819,
        "placeId": "LKjs8YA7",
        "streetName": "Loresho Close",
        "propertyName": "Park Villas"
}

Full example payload for an ecommerce transaction:

{
    "id": "{{uniqueTransactionId}}",
    "useCase": "e-commerce",
    "locationId": "WtyVrLr3yn",
    "value": 185500,
    "user": {
        "firstName": "Gift",
        "lastName": "Moore",
        "phone": "+234xxxxx" // It is important to provide your actual phone number, as a message will be sent to this number
    },
    "properties": {
        "brand": "acme",
        "branch": "thehub",
        "paymentMethod": "cash",
        "sendToQueue": true,
        "basket": [
            {
                "sku": "RF67DESL1/XFA",
                "value": 180000,
                "name": "RF67DESL FDR with Twin Cooling Plus, 491 L",
                "description": "Refrigerator is designed to improve the way you store food through an innovative 2-Door system.",
                "category": "fridge",
                "quantity": 1
            },
            {
                "sku": "MG28J5255GS/SM",
                "value": 5500,
                "name": "MW5200J Grill Microwave Oven with Healthy Steam, 28 L",
                "description": "Enjoy the flexibility to bake and microwave – all from one appliance",
                "category": "microwave ovens",
                "quantity": 1,
                "weight": "1 kg"
            }
        ],
        "shipping": {
            "cost": 120,
            "class": "Flat rate",
            "expectedDeliveryDate": "2019-08-12T09:42:22.526Z"
        }
    }
}

IMPORTANT: For production please switch this endpoint to https://server.okhi.co/v5/interactions

PreviousAPI ReferenceNextChangelog