API Reference

Webhooks

Status Updates

Kosmo uses webhooks to notify your application when a delivery event happens. Webhooks are particularly useful to handle updates asynchronously and let you react to events such as when your order has been assigned, picked up or completed.

Important: We send an update when the status of an order or one of its stops has been changed.

What are Webhooks?

Exposing a webhook endpoint on your application allows us to push real-time notifications to your server. Kosmo uses HTTPS to send all the relevant event information as a JSON body giving you the freedom of executing the adequate actions.

Webhook endpoint

A webhook endpoint is nothing more than a POST route in your application e.g https://yourdomain.com/webhooks/kosmo.

📘Endpoint registration

In the current version, please share with us your Production and Sandbox endpoints via email at [email protected].

Signature

We encourage you to use signature to check a request's validity. To do it you need to concatenate following fields: eventId, orderId, timestamp (without space). Then use HMAC SHA256, encoded via base64.

For example, having the fields like:

  • orderId: SG-19ALqYm4s6P
  • timestamp: 2023-02-23T04:22:15Z
  • eventId: 9ddafe4f-010b-43e9-a0b4-baad0c46d9de
    And secret token as "whk_UAzxUOOZOrtwVc9t4k8k5wbanrsGIbm", your signature will be "xQ9NddICmM1PeGZKrhpdlWz2ILz4X4iw8t4oSAYmueU=".

You can refresh your secret token in the develop page or by contacting us.

Tips & Suggestions

Since webhooks are sent through the network, there is a change that an earlier created webhook will be received after the following one, causing the wrong status.

To avoid that, there is the solution:

  1. Save timestamp of webhook in your order in the order details in your database.
  2. When a new webhook arrives, you compare it with the value in db.
  3. If new timestampis bigger than the current one, proceed with status update

Local development

As the payload is sent over an HTTPS request, it is not possible to register a local endpoint.

We encourage you to use Ngrok as an HTTP proxy. Once installed, the command ngrok http {APPLICATION_PORT} will provide you with HTTP/HTTPS url forwarding request to the specified port.

As always, we are available to support you through every step of the application!