Manage Subscriptions

Create a subscription

curl
JavaScript
PHP
Python

curl -X POST https://staging.api.v2.wino.fr/webhooks/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WINO_API_KEY" \
  -d '{ "shopId": "<your shop ID>", "url": "https://example.com/wino-webhooks", "clientState": "<a secret of yours>" }'

const response = await fetch(
  "https://staging.api.v2.wino.fr/webhooks/subscriptions",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.WINO_API_KEY}`,
    },
    body: JSON.stringify({
      shopId: "<your shop ID>",
      url: "https://example.com/wino-webhooks",
      clientState: "<a secret of yours>",
    }),
  },
);
if (!response.ok) throw new Error(await response.text());
const subscription = await response.json();

$response = file_get_contents('https://staging.api.v2.wino.fr/webhooks/subscriptions', false, stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => "Content-Type: application/json\r\nAuthorization: Bearer " . getenv('WINO_API_KEY'),
    'content' => json_encode([
      'shopId' => '<your shop ID>',
      'url' => 'https://example.com/wino-webhooks',
      'clientState' => '<a secret of yours>',
    ]),
    'ignore_errors' => true, // keep the error message when the API answers with an error status
  ],
]));
// $http_response_header[0] is the status line, for example "HTTP/1.1 201 Created"
$subscription = json_decode($response, true);

import os
import requests

response = requests.post(
    "https://staging.api.v2.wino.fr/webhooks/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['WINO_API_KEY']}"},
    json={
        "shopId": "<your shop ID>",
        "url": "https://example.com/wino-webhooks",
        "clientState": "<a secret of yours>",
    },
)
response.raise_for_status()
subscription = response.json()

Body field	Required	Description
`shopId`	yes	The shop to follow
`url`	yes	The URL to notify. It must be a valid `http` or `https` URL, not `localhost`, and 255 characters at most
`clientState`	no, but set it	A secret of your choice (255 characters at most), sent back in every notification. Your receiver checks it to know the notification comes from Wino (see Receive notifications)
`disabled`	no	`true` to create it paused. Default: `false`

Any other field is refused. The response is 201 Created with the subscription:

{
  "id": "0b7e…",
  "createdAt": 1793869920000,
  "updatedAt": 1793869920000,
  "userId": "…",
  "url": "https://example.com/wino-webhooks",
  "clientState": "<a secret of yours>",
  "shopId": "<your shop ID>",
  "disabled": false,
  "settings": {
    "Product": true,
    "Variant": true,
    "VariantPrice": true,
    "StockActivity": true,
    "Customer": false,
    "…": false
  }
}

createdAt and updatedAt are timestamps in milliseconds. userId identifies the account behind the key that created the subscription. To follow several shops, create one subscription per shop.

The POST doesn't accept settings: a new subscription starts with the default kinds below. To choose other kinds, create it, then send a PATCH.

localhost is refused. To test from your computer, expose your local server through a tunnel service that gives you a public HTTPS URL, and subscribe that URL.

Turn kinds on or off with PATCH. Only the kinds you send change (subscriptionId is the id returned when you created it):

curl
JavaScript
PHP
Python

curl -X PATCH https://staging.api.v2.wino.fr/webhooks/subscriptions/<subscription id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WINO_API_KEY" \
  -d '{ "settings": { "Customer": true, "SalesReceipt": true } }'

const response = await fetch(
  `https://staging.api.v2.wino.fr/webhooks/subscriptions/${subscriptionId}`,
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.WINO_API_KEY}`,
    },
    body: JSON.stringify({ settings: { Customer: true, SalesReceipt: true } }),
  },
);
if (!response.ok) throw new Error(await response.text());

$response = file_get_contents("https://staging.api.v2.wino.fr/webhooks/subscriptions/$subscriptionId", false, stream_context_create([
  'http' => [
    'method' => 'PATCH',
    'header' => "Content-Type: application/json\r\nAuthorization: Bearer " . getenv('WINO_API_KEY'),
    'content' => json_encode(['settings' => ['Customer' => true, 'SalesReceipt' => true]]),
    'ignore_errors' => true,
  ],
]));

import os
import requests

response = requests.patch(
    f"https://staging.api.v2.wino.fr/webhooks/subscriptions/{subscription_id}",
    headers={"Authorization": f"Bearer {os.environ['WINO_API_KEY']}"},
    json={"settings": {"Customer": True, "SalesReceipt": True}},
)
response.raise_for_status()

PATCH also changes url, clientState, disabled or shopId. It ignores the fields it doesn't know, without an error: check the subscription it returns. If you change clientState, keep accepting the old value for 5 minutes: notifications still carry it until the change applies. PUT replaces the whole subscription with a body like the POST one, and resets settings to the defaults. Send clientState again: without it, PUT removes it. Without disabled, PUT also turns a paused subscription back on.

List, get and delete

curl
JavaScript
PHP
Python

# List your subscriptions
curl https://staging.api.v2.wino.fr/webhooks/subscriptions \
  -H "Authorization: Bearer $WINO_API_KEY"

# Delete one
curl -X DELETE https://staging.api.v2.wino.fr/webhooks/subscriptions/<subscription id> \
  -H "Authorization: Bearer $WINO_API_KEY"

const headers = { Authorization: `Bearer ${process.env.WINO_API_KEY}` };

// List your subscriptions
const response = await fetch(
  "https://staging.api.v2.wino.fr/webhooks/subscriptions",
  { headers },
);
if (!response.ok) throw new Error(await response.text());
const subscriptions = await response.json();

// Delete one
const deletion = await fetch(
  `https://staging.api.v2.wino.fr/webhooks/subscriptions/${subscriptionId}`,
  { method: "DELETE", headers },
);
if (!deletion.ok) throw new Error(await deletion.text());

$auth = 'Authorization: Bearer ' . getenv('WINO_API_KEY');

// List your subscriptions
$response = file_get_contents('https://staging.api.v2.wino.fr/webhooks/subscriptions', false, stream_context_create([
  'http' => ['method' => 'GET', 'header' => $auth, 'ignore_errors' => true],
]));
$subscriptions = json_decode($response, true);

// Delete one
file_get_contents("https://staging.api.v2.wino.fr/webhooks/subscriptions/$subscriptionId", false, stream_context_create([
  'http' => ['method' => 'DELETE', 'header' => $auth, 'ignore_errors' => true],
]));

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['WINO_API_KEY']}"}

# List your subscriptions
response = requests.get("https://staging.api.v2.wino.fr/webhooks/subscriptions", headers=headers)
response.raise_for_status()
subscriptions = response.json()

# Delete one
requests.delete(f"https://staging.api.v2.wino.fr/webhooks/subscriptions/{subscription_id}", headers=headers).raise_for_status()

The list contains only the subscriptions created with your key. With an id, you can also read, change or delete another subscription of a shop your key accesses (for example the one of the shop's online store): check its shopId and url before changing it. PUT makes you its owner. Errors use HTTP status codes: see Errors.

Create a subscription​

List, get and delete​

Create a subscription

List, get and delete