Webhooks allow you to subscribe to specific types of events. For example, when an order is completed. Details of the event, including data related to the object (or objects) are sent directly to a callback URL when the event occurs. This allows third party applications to receive real time updates without having to poll for changes.
Webhooks are created at a company level and for each client
application that uses them. You may provide
if you do not wish to receive all events for a topic for a whole
company or other condition. See
for more information.
Create a webhook
must be one of the
must be one of
headers can be one of
X-*, but not
Applications may have more than one webhook registered. Each having their own callback URL. Multiple webhooks can be created against the same topic. This will cause multiple events to be emitted with the same data. This may be useful to receive the same event to be delivered to multiple addresses.
is an optional attribute to filter events you wish to receive. In
the case above only completed orders that were created under the
sites with one of those IDs will be emitted.
is specified then all events related to a
will be emitted.
See Filtering for a full description.
Update a webhook
can be updated on an existing webhook.
Only attributes that are specified will be updated (replaced). All of
the same validation as creating a webhook apply. i.e. When changing the
you must provide the complete new
filter, you cannot edit part of the
Updating a webhook does not affect events that have already been
emitted but not yet received by the
Delete a webhook
Note: If there are events in the queue that have yet to be delivered deleting the webhook will not remove them from the queue and they will still try to be delivered.
Testing a webhook
A test message will be sent to the
of the webhook. It is not guaranteed that this message will be
attempted to be delivered immediately. It will be queued like any
other event. For practical purposes this should be close to
The test payload will be in the
of the webhook and include the
headers but is not
expected to have any useful information relating to the
both in structure and data.
Webhook topics are available for the following entities:
Filtering is optional (to receive all events for a topic). Or you may use one or a combination of multiple filters.
All topics allow filtering by site ID. Only events that apply to at least one of the site IDs will be emitted.
site_ids is provided, there must be at least one element.
Some topics allow additional filters on attributes. Webhooks are only emitted if at least one of the attributes have changed.
attributes is provided, there must be at least one element.
See the individual entities for more information.
In most cases webhooks are delivered almost immediately after the
event. However, if any of the following cases occur when sending the
- The server cannot make a connection within 3 seconds.
- The request could not be completed within 10 seconds.
- The response code from the request was not
Then the webhook event is marked as failed and will try again later.
To prevent many webhook requests from overwhelming a server that might already be under too much load each retry will create an ever increasing time between each retry of a single webhook.
Up to 30 retries will be executed before the webhook event is permanently deleted from the queue. These times are:
- Immediately when the event occurs.
- 1 minute delay before first retry.
- 2 minute delay before second retry.
- 4 minute delay before third retry.
- 8 minute delay before forth retry.
- 15 minute delay before each retry until 30 total retries.
Requests made to the
of your webhook should be
verified to ensure they have not been tampered with and are coming
In each event will be a
header which contains a HMAC (using sha256). To verify the request
you need the
which can be found in the configuration page for your app on Kounta.
Using the body of the request and your signature token you will be able to verify the request. An example in PHP would look like:
$headers['X-Kounta-Signature'] == hash_hmac('sha256', $body,
Webhook headers can contain special values that cause their values to be calculated at the time the webhook is created. For example:
A value can only contain a single special value listed below. It cannot be contained in another string.
Provides the epoch time in milliseconds:
Provides the epoch time in whole seconds:
Generate a hash-based message authentication code. There are several options that can be provided in the form of a query string. For example:
algocan be any of the supported hashing algorithms listed here. If not provided the default is
datamust be one of the other special values (without the preceeding
@) such as
TimeInMillis. You may also use
Bodywhich will use the JSON/XML body as a string. If not provided the default is
asmust be one of
hex. If not provided the default value is