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 :

GraphQL
JavaScript
PHP

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.