WebHook
Use webhooks to be notified about events that happen during "get out request" process.
Webhook terminology
An event is a "get out request" 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 "get out request". When the event occurs (for example when a "get out request" is delivered), WineSitting creates an Event object. This object contains all the relevant information about what just happened, including the type (getoutrequest, ...), the event (create or update) and the data associated with that event (the complete updated "get out request" object, same result of retrieve a "get out request"). WineSitting then sends the Event object to URL of your account’s webhooks settings via an HTTP POST request.
All event types are descibed 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 "get out request") are reported synchronously to your code and don’t require webhooks.
When a "get out request" 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
The most common mistake with webhooks is providing the wrong URL in the Dashboard. Webhooks are configured inside API REST account settings of the Dashboard : https://app.winesitting.com/apiKey.
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. You can have multiple API keys with different Webhook URL.
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 when HTTP status code is different of 2xx 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 |
The webhook event type
| Webhook event type | Description |
|---|---|
| GETOUTREQUEST | All events concerning Get Out Request (for example when a Get Out Request is delivered) |
| BOTTLE | Only on create (deprecated, will be removed Q3 2024) |
| PUTAWAY | Only on create |
The webhook event operation
| Webhook event operation | Description |
|---|---|
| CREATE | Create operation (for example when a new Get Out Request is created) |
| UPDATE | Update operation (for example when the status of a Get Out Request is changed) |