Getting started

Between the Karhoo Platform and DMS's are two distinct types of API endpoints:

• Karhoo endpoints
  These are hosted by Karhoo and used by DMS's to push asynchronous updates to Karhoo.
• DMS endpoints
  These are hosted by the Supply Partner for Karhoo to use to request vehicle availability, quotes and bookings.

Security

Authentication is handled differently for these two classes of endpoints.

Karhoo Hosted Endpoints

Endpoints hosted by karhoo are authenticated using the same mechanism as all Karhoo Platform APIs. See How to authenticate for details.

DMS Hosted Endpoints

For DMS endpoints Karhoo signs requests using a HMAC. The HMAC signature digest is computed on the payload content using the supplied secret key (Please contact us if you have not been provided a secret key). This SHA512 hash is sent as lowercase hexits in the x-karhoo-request-signature header and should be used to validate all requests from Karhoo.

🚧

Always check each request

It is important to verify each request body to avoid man-in-the-middle attacks or fake requests.

❗️

You must hash the entire response body

Failing to account for linefeed (LF) or new line (NL) characters when comparing hash signatures will result in a failed cryptographic check.

The following is copied from a golang playground example of how we would sign our X-Karhoo-Request-Signature header with the shared secret we will provide to you.

package main

import (
	"crypto/hmac"
	"crypto/sha512" // not to be confused with sha256
	"encoding/hex"
	"encoding/json"
	"fmt"
)

// Please do not set your key to this example in production
const (
	signature         string = "8816883ca05dda771ddf522c26a958b262ebe52753ed5fcc87828b24aff49b3369aa005a2f664a87f1a1958e0f44121f1643aebcba35a32ff2d921eaad5e4ad7"
	exampleSecretKey  string = "EAlOTQ1IHwansbPn0cUOPyQYrONmuOAu"
	sampleRequestBody string = `{"attempt_number":0,"checksum":"c7fe6dfefc4765337e8e0a31bbe1e49c2addd676c2f1b764100a0b27fb6f296c440ecb9c8f4aec552c86babe24ae1d7040cde399cc5153600799257a8a16f845","data":"{\"status\":\"ARRIVED\",\"trip_id\":\"c2374749-e983-4d8b-9312-1ca06a5ffe37\"}","event_type":"TripStatus","id":"5948ec35-a071-4f71-9416-c607d0120ca8","sent_at":"2020-12-02T00:04:58.711Z"}`
)

type Event struct {
	ChecksumHEX string `json:"checksum"`
	Data        string `json:"data"`
}

// HashRequestBody represents a function similiar to how we sign our signature
func HashRequestBody(body []byte, secretKey []byte) (string, error) {
	mac := hmac.New(sha512.New, secretKey)
	_, err := mac.Write(body)
	if err != nil {
		return "", err
	}
  
	return hex.EncodeToString(mac.Sum(nil)), nil
}

func main() {
	// we need to generate our own hash to compare against the signature
	hash, err := HashRequestBody([]byte(sampleRequestBody), []byte(exampleSecretKey))

	if err != nil {
		panic(err)
	}

	// will print true if the signature matches the hash we computed and our data is secure.
	fmt.Println(signature == hash)

	// we can go a step further and check the contents of the event type
	var evt Event
	if err := json.Unmarshal([]byte(sampleRequestBody), &evt); err != nil {
		panic(err)
	}
  
	sha := sha512.Sum512([]byte(evt.Data))
	checksum := hex.EncodeToString(sha[:])

	fmt.Println(checksum == evt.ChecksumHEX)
}

Contact the Karhoo team for help with the above.

API endpoints

DMS API Endpoints

The minimum set of DMS Hosted APIs are Quotes , Booking, Trip Updates and Cancellation. These are implemented as webhooks within your platform.

📘

Availability and ETA are optional

These are only used when ETA is not included in your Quotes endpoint implementation and you would like to offer On Demand ASAP bookings.

Karhoo hosted endpoints

Our Supply API provides an option for our supply partners to push Trip Updates to us directly instead of us requesting this data from their DMS API. This is optional but highly recommended to implement to reduce our polling rate and burden it may cause for your API.

Swagger Spec & Auto Generation

We've made the swagger spec available here which that defines our hosted endpoints as well as what we expect our Supply Partners to implement as webhooks.

We encourage you to use this to autogenerate as much boilerplate as is useful to reduce the workload of writing the integration.