ZEST Webhook Event Notifications

Webhooks allow you to subscribe to certain events that happen in ZEST. Rather than polling the API to check for changes in data (e.g a new order, or an updated product), you can instead just subscribe an endpoint to the event you are interested in, and ZEST will notify you with a push notification - POSTing relevant data to the endpoint registered against the webhook.

Format

Unlike other ZEST APIs, webhooks POST a JSON payload to the configured endpoint.

Supported Events

There are numerous supported events that you can elect to subscribe to. These include:

Event Type	API Event Name	Description
New Order	NewOrder	A new Order has been created
Updated Order	UpdatedOrder	An existing Order has been updated
New User	NewUser	A new User has been created
Updated User	UpdatedUser	An existing User has been updated
Updated Product	UpdatedProduct	A Product has been created or updated
Deleted Product	DeletedProduct	An existing Product has been deleted
Updated Category	UpdatedCategory	A Category has been created or updated
Deleted Category	DeletedCategory	An existing Category has been deleted

Payloads

The payload will be a consistent format for all of events type. It will consist of:

Type	Description
The Events Array	The details of the events that you've subscribed to
Entropy	A random string to make the payload more secure

Example Payload

{
    "data": {"keys" : ["2290", "4441", "foo-bar"]},
    "webhook": "UpdatedProduct",
    "entropy": "8ww1ph5y",
}

The x-zest-signature Header

Your application needs to verify that any incoming request to the specified endpoint is legitimate - that it definitely came from our servers, and is not being faked.

To prove the request came from our servers, we provide a a hashed signature of the payload - passed in the headers of each request as x-webhook-signature.

To verify the signature: 1. remove any leading or trailing whitespaces from the payload 2. create a hash the payload using HMACSHA256 with your webhook secret key. If you do not have a secret, contact us to request one.

If the resulting hash does not match the x-webhook-signature header, then this is not a legitimate request and should be ignored (this is worth investigating as someone is likely trying to spoof & send fake requests to your software).

Registering an endpoint

To register an endpoint against a webhook event, you can either:

1. Manually register the endpoint via the website administration tool - visiting $domain/admin/webhook_list.
2. Using the Webhooks resource in the Data API.

You only need to register the endpoint once. From then on, ZEST will send a push notification to that endpoint every time the event is fired.

Administration tool

1. Click the Connect New Webhook button
2. Select which even you would like to observe
3. Specify the endpoint you would like us to notify when this event is fired.

Via the API

Your app can programatically subscribe endpoints to events by sending a POST request to the /Webhooks endpoint.

See the Webhooks resource documentation for more details.