Webhooks ShipStation

Comment créer, gérer et utiliser des webhooks qui seront envoyés dans un terminal lorsque certains événements se produiront dans ShipStation.

Si vous utilisez l'API REST de ShipStation pour communiquer des informations relatives aux commandes, ou si vous utilisez un système tiers qui souhaite extraire des données de ShipStation, il peut être avantageux pour vous de configurer des webhooks. Une fois les webhooks configurés, ShipStation peut envoyer des alertes lorsque certains événements se produisent dans votre compte. Ces alertes permettront de guider le système vers un terminal qui pourra être utilisé pour recueillir les données du compte ShipStation.

Principes fondamentaux des webhooks

Les webhooks sont un processus API qui permet à ShipStation d'envoyer des mises à jour automatiques vers l'URL d'un terminal cible lorsque certaines actions se produisent dans votre compte ShipStation. Lorsqu'ils sont déclenchés, ShipStation effectue un appel API POST pour livrer une charge utile de données à l'URL cible qui comprendra un suivi resource_url pouvant être utilisé pour recueillir des informations spécifiques relatives aux commandes ou aux expéditions. Un webhook enverra la charge utile à l'URL cible quelques minutes après l'action qui l'a déclenché.

Vous pouvez créer 4 types de webhooks dans ShipStation :

  • Pour les nouvelles commandes (ORDER_NOTIFY)

  • Pour les nouveaux articles (ITEM_ORDER_NOTIFY)

  • Pour les commandes expédiées (SHIP_NOTIFY)

  • Pour les articles expédiés (ITEM_SHIP_NOTIFY)

Les webhooks de type Pour les nouvelles commandes et Pour les nouveaux articles sont liés aux données de commande. Ces webhooks se déclenchent dès qu'une nouvelle commande est créée dans ShipStation avec tout autre statut que En attente de paiement ou lorsque le statut d'une commande passe de En attente de paiement à n'importe quel statut autre que Annulée.

  • La charge utile d'un webhook sera créée pour chaque action d'importation qui crée au moins une nouvelle commande payée.

  • Toutes les commandes créées en même temps seront incluses dans la charge utile d'un seul webhook.

Les types de webhooks Pour les commandes expédiées et Pour les articles expédiés sont liés aux données d'expédition. Ces webhooks se déclenchent lorsqu'une nouvelle étiquette d'expédition sortante est générée pour une commande. Les webhooks ne sont pas déclenchés pour les traitements, que ce soit par l'intermédiaire d'un partenaire comme FBA ou de traitements créés à l'aide de l'action Marquer comme expédié.

  • Si vous créez des expéditions individuellement, chaque expédition déclenchera son webhook.

  • Si vous créez des expéditions en lots, chaque lot déclenchera un seul webhook.

Créer des webhooks

Vous pouvez créer de nouveaux webhooks dans votre compte ShipStation de deux manières différentes :

  • Appels d'API

  • Paramètres du compte ShipStation

Cette section explique comment créer des webhooks à partir de la page Paramètres ShipStation. Pour plus d'informations concernant l'utilisation des appels d'API, consultez notre documentation détaillée sur les API et découvrez comment répertorier les webhooks, vous abonner à un webhook et vous désabonner des webhooks.

Pour créer un webhook dans ShipStation :

  1. Sélectionnez Webhooks dans la série d'options.

    Partenaires d'intégration avec icône des webhooks encadrée en rouge

    Remarque

    Si vous n'avez pas encore créé de webhooks, l'option sera grisée.

  2. Cliquez sur Ajouter un webhook.

    Menu Webhooks d'intégration avec le bouton « Ajouter un webhook » encadré en rouge.
  3. Définissez le Nom (100 caractères maximum), le Type, si le webhook s'applique à toutes les boutiques ou à une boutique spécifique et l'URL cible (200 caractères maximum).

    Formulaire de webhook des partenaires d'intégration
  4. Cliquez sur Enregistrer pour créer le webhook après avoir saisi les détails.

Supprimer des webhooks

Vous pouvez supprimer les webhooks existants de votre compte ShipStation de deux manières différentes :

  • Appels d'API

  • Paramètres du compte ShipStation

Cette section explique comment supprimer des webhooks à partir de la page Paramètres ShipStation. Pour plus d'informations concernant l'utilisation des appels d'API, consultez notre documentation détaillée sur les API et découvrez comment supprimer des webhooks.

Pour supprimer un webhook dans ShipStation :

  1. Sélectionnez Webhooks dans la série d'options.

    Partenaires d'intégration avec icône des webhooks encadrée en rouge
  2. Cliquez sur Supprimer à côté du webhook dont vous n'avez plus besoin.

    Menu Webhooks avec le bouton « Supprimer » encadré en rouge.
  3. Cliquez sur Oui, supprimer pour confirmer la suppression.

    Les webhooks retirent la fenêtre contextuelle de confirmation avec le bouton « Oui, supprimer » encadré en rouge.

Modifier les webhooks

Indépendamment de la manière dont le webhook a été créé, vous ne pouvez modifier un webhook existant qu'à partir des paramètres de votre compte ShipStation.

Pour modifier un webhook existant :

  1. Sélectionnez Webhooks dans la série d'options.

    Partenaires d'intégration avec icône des webhooks encadrée en rouge
  2. Cliquez sur Modifier à côté du webhook que vous souhaitez modifier.

    Menu Webhooks avec le bouton « Modifier » encadré en rouge.
  3. Mettez à jour le Nom (100 caractères maximum), le Type, si le webhook s'applique à toutes les boutiques ou à une boutique spécifique et l'URL cible (200 caractères maximum), s'il y a lieu.

  4. Cliquez sur Enregistrer pour mettre à jour le webhook.

Utilisation des charges utiles des webhooks

Lorsqu'un webhook est déclenché, ShipStation effectue un appel d'API POST vers l'URL cible.

Cet appel inclut une charge utile liée à l'action et aux données récemment créées :

  • resource_url : le terminal à contacter pour recueillir les données relatives à l'action qui a déclenché le webhook. resource_url contient plusieurs paramètres d'URL :

    • storeId : identifiant interne de ShipStation pour la boutique. storeId ne sera pas inclus si le webhook s'applique à toutes les boutiques.

    • importBatch ou batchId : identifiants internes de ShipStation pour l'action d'importation (pour les webhooks COMMANDE) ou l'action de création d'étiquette (pour les webhooks EXPÉDITION).

    • includeOrderItems ou includeShipmentItems : contrôle si les articles sont inclus dans la réponse lorsque vous contactez resource_url. Si vous utilisez un webhook ARTICLE, celui-ci sera défini sur True.

  • resource_type : type de webhook qui a déclenché la charge utile.

Pour utiliser la charge utile du webhook, vous devez passer un appel d'API GET à la REST API de ShipStation qui utilise resource_url comme terminal. Lorsque vous effectuez cet appel d'API, vous devez inclure un en-tête d'authentification, tout comme les autres appels d'API effectués pour ShipStation. Consultez notre documentation détaillée sur l'API pour plus de renseignements concernant l'authentification de l'API.

Lors de la communication avec resource_url, la réponse suivra la même structure que l'appel Faire la liste des commandes (pour les webhooks COMMANDE) ou l'appel Faire la liste des expéditions (pour les webhooks EXPÉDITION).

Voici quelques exemples de charges utiles pour les webhooks :

Pour les nouvelles commandes (ORDER_NOTIFY)

{"resource_url":"https://ssapiX.shipstation.com/orders?storeID=123456&importBatch=1ab23c4d-12ab-1abc-a1bc-a12b12cdabcd","resource_type":"ORDER_NOTIFY"}

Pour les nouveaux articles (ITEM_ORDER_NOTIFY)

{"resource_url":"https://ssapiX.shipstation.com/orders?storeID=123456&importBatch=1ab23c4d-12ab-1abc-a1bc-a12b12cdabcd&includeOrderItems=True","resource_type":"ITEM_ORDER_NOTIFY"}

Pour les commandes expédiées (SHIP_NOTIFY)

{"resource_url":"https://ssapiX.shipstation.com/shipments?storeID=123456&batchId=12345678","resource_type":"SHIP_NOTIFY"}

Pour les articles expédiés (ITEM_SHIP_NOTIFY)

{"resource_url":"https://ssapiX.shipstation.com/shipments?storeID=123456&batchId=12345678&includeShipmentItems=True","resource_type":"ITEM_SHIP_NOTIFY"}