Skip to main content

Using webhooks

Webhooks are a way to get notified when an entity is created or updated in Wino.

Webhooks can be used to:

  • Keep a third party system in sync with Wino (an online store for instance)
  • Send notifications to clients
  • Collect data for analytics purposes
  • ...

How webhooks works#

You first have to subscribe to the Wino webhooks through our API, then, when a change happens in the Wino system, you receive a notification, through an http POST call to an url you defined during the subscrition.

Subscribe to webhooks#

note

The API calls to manage your webhooks subscriptions need to be authenticated or you will receive an Unauthorized error. Take a look at Authentication.

To create a subscription, you can run the following command, replacing [your-auth-token], [your-shop-id] and [the-url-to-notify].

curl \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [your-auth-token]" \
-d '{ "shopId": "[your-shop-id]", "url": "https://[the-url-to-notify]" }' \
https://wino-api-url/webhooks/subscriptions

You can also provides an optional clientState string property in the request body, that is passed back in the notification message for your subscription. This can be used to verify that the request is indeed coming from the source you trust, which in this case is Wino. If you do so, we recommend you to send an encrypted value.

The API will return a response with the created subscription data in the response body.

Notifications and change types#

Once the POST is issued against the subscription API, the url will be notified each time a modification related to the shop id happens. The notification body will take the following form:

{
"clientState": "an optional value you can pass during subscription",
"source": {
"shopId": "the-shop-id-causing-the-update",
"deviceId": "the-device-id-causing-the-update"
},
"kind": "The type of entity updated",
"data": {
"id": "the-entity-id",
// ...The entity properties
}
}

Example#

After the create or the update of a variant, you will receive this kind of http request body:

{
"clientState": "optional value",
"source": {
"shopId": "20258224-05f3-49a7-9299-fab4acb89ee5",
"deviceId": "b1fd5f30-a879-40a0-9a86-46804c16ed12"
},
"kind": "Variant",
"data": {
"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"
}
}

You can note the presence of the relationships in the form of an id. These ids allow you to perform the following GraphQL call to retrieve the linked entities, if needed.

Managing your subscriptions#

You can use the following REST resources to manage your subscriptions:

  • GET https://wino-api-url/webhooks/subscriptions
  • GET https://wino-api-url/webhooks/subscriptions/{subscription-id}
  • POST https://wino-api-url/webhooks/subscriptions
  • PUT https://wino-api-url/webhooks/subscriptions/{subscription-id}
  • PATCH https://wino-api-url/webhooks/subscriptions/{subscription-id}
  • DELETE https://wino-api-url/webhooks/subscriptions/{subscription-id}

Additional notes#

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

  • Some delay is to be taken into account before notifications are received. The delay can be up to few minutes.
  • Today, only the product catalog schemas Product, StockActivity, 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.
  • If a notification fails to be sent, a new notification attempt will be scheduled. If there are too much consecutive failures (for instance if your url is not valid anymore), the webhook subscription may be automatically disabled.