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 have 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"
    // ...theEntityProperties
  }
}

Example

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

{
  "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}

Supported schemas

Today, only the following product catalog schemas are supported by the Webhook system:

Additional notes

  • Any write query made to the Wino API can trigger related webhook notification. So if you create, for instance, a stock activity through the GraphQL, a webhook notification for this stock activity will be triggered.

  • Some delay is to be taken into account before notifications are received. The delay can be up to few minutes.

  • 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 might be automatically disabled.