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.
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: orderId, timestamp, eventType.(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.
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!