Webhooks ShipStation

Comment créer, gérer et utiliser des webhooks qui seront publiés sur un point de terminaison lorsque certains événements se produisent dans ShipStation.

Si vous utilisez l'API REST de ShipStation pour communiquer des informations sur les commandes, ou si vous utilisez un système tiers qui tente tirer des données de ShipStation, il vous sera peut-être utile de mettre en place des webhooks. Une fois que vous avez configuré des webhooks, ShipStation peut envoyer des alertes lorsque certains événements se produisent dans votre compte. Ces alertes vous aideront à guider le système vers un point de terminaison qui peut être utilisé pour recueillir des données à partir du compte ShipStation.

Principes de base des liens de rappel HTTP

Les webhooks sont un processus d'API qui permet à ShipStation de diffuser des mises à jour en direct vers un point de terminaison URL cible lorsque certaines actions se produisent dans votre compte ShipStation. Une fois déclenché, ShipStation effectuera un appel POST API pour envoyer des données utiles à URL cible qui inclura un suivi resource_url qui peut être utilisé pour recueillir des informations spécifiques liées aux commandes ou aux expéditions. Un webhook publiera les données utiles sur URL cible quelques minutes après l'action qui l'a déclenchée.

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 types de webhook pour les nouvelles commandes et pour les nouveaux articles sont liés aux données de commande. Ces webhooks se déclenchent chaque fois qu'une nouvelle commande est créée dans ShipStation avec un statut autre que En attente de paiement, ou lorsqu'une commande En attente de paiement est mise à jour à un statut autre que Annulé.

  • Une charge utile de 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 une seule charge utile de webhook.

Les types de webhook pour les commandes expédiées et pour les articles expédiés se réfèrent 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 seront pas déclenchés pour les exécutions, que ce soit par le biais d'un partenaire de service d'exécution comme Expédié par Amazon ou des exécutions réalisées à l'aide de l'action Marquer comme expédié.

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

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

Créer des liens de rappel HTTP

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

  • Appels API

  • Paramètres du compte ShipStation

Cette section explique comment créer des webhooks à partir de la page de paramètres de ShipStation. Pour en savoir plus sur l'utilisation des appels API, consultez nos documents détaillés sur l'API pour plus de détails sur la façon de répertorier les webhooks, de s'abonner à un webhook et de se désabonner des webhooks.

Pour créer un webhook dans ShipStation :

  1. Sélectionnez webhooks parmi les options.

    Icône Partenaires d'intégration avec webhooks en surbrillance

    Remarque

    Si aucun webhook n'a été créé, l'option sera grise.

  2. Cliquez sur Ajouter un webhook.

    Menu Intégration de webhooks avec le bouton Ajouter un webhook en surbrillance.
  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 webhook des Partenaires d'intégration
  4. Cliquez sur Enregistrer pour créer le webhook après avoir rempli les informations.

Supprimer les liens de rappel HTTP

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

  • Appels API

  • Paramètres du compte ShipStation

Cette section explique comment supprimer les webhooks à partir de la page de paramètres de ShipStation. Pour en savoir plus sur l'utilisation des appels API, consultez nos documents détaillés sur les API pour plus de renseignements sur la suppression des webhooks.

Pour supprimer un webhook dans ShipStation :

  1. Sélectionnez webhooks parmi les options.

    Icône Partenaires d'intégration avec webhooks en surbrillance
  2. Cliquez sur Supprimer à côté du webhook dont vous n'avez plus besoin.

    Menu Webhooks avec le bouton Supprimer en surbrillance.
  3. Cliquez sur Oui, je veux le supprimer pour confirmer l'action.

    Webhooks supprime la fenêtre contextuelle de confirmation avec le bouton Oui, je veux le supprimer en surbrillance.

Modifier les liens de rappel HTTP

Quelle que soit la manière dont le webhook a été créé, vous ne pouvez modifier un webhook existant que par le biais des paramètres de votre compte ShipStation.

Pour modifier un webhook existant :

  1. Sélectionnez webhooks parmi les options.

    Icône Partenaires d'intégration avec webhooks en surbrillance
  2. Cliquez sur Modifier à côté du webhook que vous souhaitez modifier.

    Menu Webhooks avec le bouton Modifier en surbrillance.
  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) selon les besoins.

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

Utilisation des charges utiles des liens de rappel HTTP

Lorsqu'un webhook est déclenché, ShipStation effectue un appel 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 : point de terminaison à contacter pour recueillir les données liées à 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 affecte toutes les boutiques.

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

    • includeOrderItems ou includeShipmentItems : contrôle si les éléments sont inclus dans la réponse lors du contact avec resource_url. Si vous utilisez un webhook d'ARTICLE, celui-ci sera défini sur Vrai.

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

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

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

Voici quelques exemples de charges utiles pour webhook :

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