Manage Webhooks

warning

This section is a work in progress.

Webhooks is the way to get notified if an entity changes in Wino and stay in sync with Wino.

Common Webhooks use cases include the following:

  • Sending notifications to clients
  • Collecting data for data-warehousing
  • Integrating with an online store
  • ...

Register a Webhooks subscription#

note

To have access to the API url and the API Key, please contact the Wino team by email at hello@wino.fr.

To save your notification URL on our system, make the following request and add your notificationUrl to it:

curl \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xxxx" \
-d '{ "notificationUrl": "https://xx.x/", "clientState": "optionalValueOf2048", "shopId": "xxx" }' \
https://europe-west1-wino-xxxx.xx.net/webhook/subscriptions

Once the POST is issued against the subscription API to create the subscription, Wino will issue a request to the notificationUrl, passing a token parameter on the query string. Subscriber needs to perform the handshake by returning token in the response body and provide status code 200:

RESPONSE

status: 200
{
"token": "xxx"
}

If Wino receives the response containing the token, the subscription is registered and webhook notifications will be sent to your notificationUrl.

Notifications and change types#

Once you register your notification URL, you will be able to receive notifications as follows:

{
"clientState": "optionalValueOf2048",
"type": "Xx",
"object": {
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"xx": "xx"
}
}

Example#

After the create or the update of a variant, you will receive this sample of data:

{
"clientState": "optionalValueOf2048",
"type": "Variant",
"object": {
"id": "4e584c64-a377-4689-aa01-7fbd32f12a44",
"archivedAt": null,
"createdAt": "2020-10-20T09:51:59.081Z",
"updatedAt": "2020-11-05T10:57:47.663Z",
"name": "33 cl",
"active": true,
"stockKeepingUnit": null,
"year": null,
"packaging": null,
"tastingNote": null,
"internalNote": null,
"purchasedPrice": 1.7,
"ean13": null,
"bulk": null,
"capacityUnit": "cl",
"capacityValue": 33000,
"capacityPrecision": 3,
"productId": "360cbbac-e9c3-4747-83bc-9c6a83b72c38",
"shopId": "20258224-05f3-49a7-9299-fab4acb89ee5"
}
}

We will then note the presence of the one-to-one relationships that are given to you. So, you will be able to perform the following GraphQL call to retrieve the linked product :

query {
product(id: "360cbbac-e9c3-4747-83bc-9c6a83b72c38") {
id
name
variant {
id
}
}
}

And receive:

{
"data": {
"product": {
"id": "360cbbac-e9c3-4747-83bc-9c6a83b72c38",
"name": "Crozes Hermitage",
"product": {
"id": "4e584c64-a377-4689-aa01-7fbd32f12a44"
}
}
}
}

Additional notes#

Before using the Webhooks system, please familiarize yourself with the following:

  • A variable delay is to be taken into account before notifications are received. In some cases, the delay can be up to a few minutes. It is linked to the time required to synchronize the shop's data on his POS application, which follows an offline-first strategy.
  • Today, only the product catalog schemas Price, Product, StockActivity, Tax, Variant and VariantPrice are compatible with the Webhook system.
  • If you have any problems using the webhooks, do not hesitate to contact customer support at the following address: help.wino.fr or by email at hello@wino.fr.

In the future, as a result of feedback from developers, we plan to make the following changes:

  • Notifications are sent in the following in a queue. If a notification fails to be sent, 10 delayed sending attempts will be scheduled. If there are 10 consecutive failures, then the Webhooks subscription is automatically deleted. A warning that the subscription will be deleted is sent to the app's emergency developer email address.
  • To guard against webhooks duplication and flooding, Wino uses webhook de-duplication. This reduces the total amount of webhooks when multiple update actions are performed against an API resource in rapid succession.