WebHooks

Use webhooks to be notified about events that happen during "order" process.

Webhook terminology

An event is an "order" update (when WineSitting start to prepare the order or deliver an order). Each occurrence has a corresponding Event object. Webhook endpoint is a unique URL defined by users to which WineSitting sends events. Webhooks refers to the overall concept of sending notifications to webhook endpoints.

Interacting with a third-party API like WineSitting can introduce two problems:

• Services not directly responsible for making an API request may still need to know the response of that request,
• Some events, like pickup or delivery and many events, are not the result of a direct API request.

Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens associated with your "order". When the event occurs (for example when an "order" is delivered), WineSitting creates an Event object. This object contains all the relevant information about what just happened, including the type (order, ...), the event (create or update) and the data associated with that event (the complete updated "order" object, same result of retrieve an "order"). WineSitting then sends the Event object to URL of your account’s webhooks settings via an HTTP POST request.

All event types are described in WebHook event type section.

When to use webhooks

Webhooks are only necessary for behind-the-scenes update process. The results of most WineSitting requests (for example creating or getting a "order") are reported synchronously to your code and don’t require webhooks.

When a "order" is being processed by WineSitting, you can do polling at fixed interval to get status update.

Sometimes polling are not adapted, and a lot of request are send uselessly to get only few order updates : in this case webhook are perfectly adapted to send only update in asynchronous way.

Configuring your webhook settings

Webhooks are configured inside API REST account settings of the Dashboard : https://app.winesitting.com/bearers.

You can enter any URL you’d like to have events sent to, but this should be a dedicated page on your server, coded per the instructions below. API Keys and Webhooks are independent.

Responding to a webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code.

WineSitting ignores all information returned in the request headers or request body as it uses "fire and forget" pattern.

No retry policy are currently supported.

Best practices

Before going live, test that your webhook is working properly on pre-production by creating test command to receiving webhook events.

If your webhook script performs complex logic, or makes network calls, it’s possible the script would time out before WineSitting sees its complete execution. As WineSitting needs to stay fast, it uses "fire and forget" pattern when sending notifications.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

The webhook event object

Attribute name	Type	Description
type	WebHook event type	Type of event
operation	WebHook event operation	Type of operation
object	One of the WineSitting object	The updated object
date		Current date

The webhook event type

Webhook event type	Description
ORDER	All events concerning order (for example when a order is delivered)
PUTAWAY	Only on create

The webhook event operation

Webhook event operation	Description
CREATE	Create operation (for example when a new order is created)
UPDATE	Update operation (for example when the status of a order is changed)