In this article we'll explain how Webhooks can be used to notify of Doshii events. App event details are available here. POS event details are available here.
The Doshii API is based on asynchronous communication. When a request is submitted, the communication with the POS at the other end is performed asynchronously.
For your App or POS to be notified of any changes, it needs to establish some callback mechanism. Doshii currently supports two types of communication - WebSockets and Webhooks.
In this article, we'll cover how webhooks can be used to be notified of Doshii events. See the following wikipedia article for more information on what a webhook actually is.
To begin, you must first create an endpoint hosted external to Doshii that will support the following:
- A POST request
- Content-Type of application/json
- Can be either HTTP or HTTPS
- Can be protected with some level of Authentication
- The endpoint must be reachable from the internet
- Support the payloads described in each of the Doshii events
- Must be capable of responding to a webhook verification check
Once you have an endpoint that is reachable from outside your corporate firewall, you will need to subscribe that webhook with Doshii and associate it to the relevant Doshii events that you are interested in receiving. See the Doshii API on how to create a webhook subscription.
The authentication details for a webhook have been broken up into the following categories to allow for flexibility in how the credentials are passed to your webhook implementation. There are 2 optional string properties that can be submitted during a webhook subscription, authenticationKey and authenticationToken. Depending on which properties are submitted will depend on how Doshii passes the credentials through in the Authorization header.
The logic is as follows:
- If both authenticationKey and authenticationToken are provided, Doshii will send a Basic Auth request with a base64 encoded string of the concatenation of the two properties separated by a colon:
- If only authenticationToken is provided, Doshii will send a Basic Auth request with a base64 encoded string of the authenticationToken:
- If only authenticationKey is provided, Doshii will treat that as the raw value for the Authorization header
- If nothing is provided in either property, no Authorization header will be sent.
When a webhook is submitted to Doshii, the webhook will be verified before it is accepted. This process requires Doshii to be able to access the webhook endpoint using the URL and credentials supplied as part of the request. In addition, it will send a query parameter called verify with a unique hashed ID. For the webhook to be verified, the webhook must respond with that hashed ID and a status code of 200.
If a webhookUrl of https://some.external.site/doshii/webhook is submitted, Doshii will immediately call the following endpoint
Doshii will expect to receive the following in the response body with a HTTP 200 OK response status
Once the webhook has been verified it will immediately become active and any events associated to that webhook that are broadcast by Doshii will cause the webhook to be invoked with the event payload.
Note that the Content-Type header on the response should also be set to application/json
Please sign in to leave a comment.