Gérer les abonnements

Créer un abonnement

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()

Champ du corps	Obligatoire	Description
`shopId`	oui	La boutique à suivre
`url`	oui	L'URL à notifier. Elle doit être une URL `http` ou `https` valide, pas `localhost`, et faire 255 caractères au plus
`clientState`	non, mais renseignez-le	Un secret de votre choix (255 caractères au plus), renvoyé dans chaque notification. Votre récepteur le vérifie pour savoir que la notification vient de Wino (voir Recevoir les notifications)
`disabled`	non	`true` pour le créer en pause. Par défaut : `false`

Tout autre champ est refusé. La réponse est 201 Created avec l'abonnement :

{
  "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 et updatedAt sont des timestamps en millisecondes. userId identifie le compte derrière la clé qui a créé l'abonnement. Pour suivre plusieurs boutiques, créez un abonnement par boutique.

Le POST n'accepte pas settings : un nouvel abonnement démarre avec les types par défaut ci-dessous. Pour choisir d'autres types, créez-le, puis envoyez un PATCH.

localhost est refusé. Pour tester depuis votre ordinateur, exposez votre serveur local via un service de tunnel qui vous donne une URL HTTPS publique, et abonnez cette URL.

Activez ou désactivez des types avec PATCH. Seuls les types que vous envoyez changent (subscriptionId est l'id renvoyé à la création) :

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 modifie aussi url, clientState, disabled ou shopId. Il ignore les champs qu'il ne connaît pas, sans erreur : vérifiez l'abonnement qu'il renvoie. Si vous changez clientState, continuez d'accepter l'ancienne valeur pendant 5 minutes : les notifications la portent encore jusqu'à ce que le changement s'applique. PUT remplace tout l'abonnement avec un corps comme celui du POST, et remet settings aux valeurs par défaut. Renvoyez clientState : sans lui, PUT le supprime. Sans disabled, PUT réactive aussi un abonnement en pause.

Lister, récupérer et supprimer

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()

La liste ne contient que les abonnements créés avec votre clé. Avec un id, vous pouvez aussi lire, modifier ou supprimer un autre abonnement d'une boutique à laquelle votre clé donne accès (par exemple celui de la boutique en ligne de la boutique) : vérifiez son shopId et son url avant de le modifier. PUT vous en rend propriétaire. Les erreurs utilisent les codes de statut HTTP : voir Erreurs.

Créer un abonnement​

Lister, récupérer et supprimer​

Créer un abonnement

Lister, récupérer et supprimer