Understand webhooks

A webhook (also called Callback URL) is a web address called when an event occurs on your account.
Ex : when you close a sale (=event), we can send automatically the sale data to a specific webhook sale.

A webhook allows a dynamic behavior like invoking one or several scripts when an event occurs.
You don’t need anymore to ask every second or minute if the event happens. Hiboutik is telling you that the event has occurred. You save resources (API calls) and time (instantly informed).
Here are some examples :
– When you close a sale, you can sync the inventory of your website or send automatically a survey to your customer.
– When you create a product, you can launch a script to add also the product into your website back-office.
– When you update a customer form, you can automatically send him an email confirming the modification.

Add webhooks

From your account, yo can add a single webhook when a sale is closed or a customer is added/modified in 'Settings/API'.
You can also create your webhooks from the API for others events. This method enables to create different webhooks for the same event with specific settings.
By default, a webhook execution is synchronous, but you can allow your webhook to be asynchronous if you configure the webhook_async setting to 1. It is particularly recommended to use asynchronous webhook if your app takes time to send a response.

The API resource to create a webhook is:

POST /webhooks

Webhooks can be different for each point of sale in a multi-stores account.

Events that can activate a webhook are :

Webhook name	Event
sale	Close of a sale
sale_item	Add a product to a sale
payment	Select/add/delete a payment method in a sale
customer	Add/modify/delete a customer form
store_credit	Add a store credit line in a customer form
product	Add/modify/delete a product form
stock_order	Receive/Unreceive a stock order (including a quantity update in a stock order)
timestamp	Start/stop a timeline
schedule	Add/modify/delete a schedule event
stock_transfer	Confirm a transfer between stores
line_item_exchange	Return/exchange a product on a sale
sale_creation	Creation of a sale
sale_deletion	Deletion of a sale

Receive webhook responses

Data are sent in POST with a x-www-form-urlencoded format to you webhooks, and are specific to the event that triggered the request.
For example, the Webhook sale will receive the data of the API resource GET /sales/{sale_id}.
If necessary, you can then use the Hiboutik API to get more information.

Synchronous webhooks

The synchronous webhooks have a 4 seconds timeout.
Your server must respond with a 'HTTP 200 OK' header.
If the timeout limit is reached or any other HTTP status is sent the request is aborted and an error will be registered.

Asynchronous webhooks

The asynchronous webhooks have a 10 seconds timeout.
Your server should respond with a 'HTTP 200 OK' header.
In addition the 201, 202 and the 204 statuses are also accepted. If the response status is different the webhook will be queued and retried 8 more times with an exponentially increasing interval from 2 up to 64 seconds. After that it will be dropped.