Subscription

The Doshii API is based on asynchronous communication. When a request is submitted, the communication with the App at the other end is performed asynchronously.

For your 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.

Authentication

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:
```
'Basic base64(authenticationKey:authenticationToken)'
```
If only authenticationToken is provided, Doshii will send a Basic Auth request with a base64 encoded string of the authenticationToken:
```
'Basic base64(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

Webhook Verification

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.

Example

If a webhookUrl of https://some.external.site/doshii/webhook is submitted, Doshii will immediately call the following endpoint

https://some.external.site/doshii/webhook?verify=eaae16a0-2100-4dc0-9223-62bdcc222345

Doshii will expect to receive the following response:

200 OK
eaae16a0-2100-4dc0-9223-62bdcc222345

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.