Workflow WebhooksWorkflow Webhooks

API pour développeurs et MCP

Tout ce que vous gérez dans l'application, vous pouvez également le gérer à partir de votre propre code ou via un assistant IA. Workflow Webhooks propose deux interfaces : une API REST et un serveur MCP. Les deux sont disponibles sur la page « Développeurs ».

Clés API

Les deux interfaces s'authentifient à l'aide d'une clé API. Sur la page « Développeurs », dans la section **« Clés API **», créez une clé et sélectionnez son niveau d'accès :

  • Accès en lecture seule : consulter la liste des webhooks, l'historique des invocations et les statistiques.
  • Lecture et écriture : vous pouvez également créer, mettre à jour et supprimer des webhooks.
  • Lire, écrire et exécuter - vous pouvez également lancer un test ou rejouer un test antérieur.

La clé complète s'affiche une seule fois, lors de sa création. Veuillez la copier à ce moment-là et la conserver en lieu sûr ; vous ne pourrez plus la consulter par la suite. Les clés sont stockées sous forme hachée, jamais en clair, et vous pouvez révoquer une clé à tout moment.

Envoyez la clé sous forme de jeton « Bearer » à chaque requête :

text
Authorization: Bearer fwk_your_key_here

Pourquoi l'exécution constitue-t-elle un niveau distinct ?

Le déclenchement d'un Webhook lance bel et bien vos Workflows Shopify Flow, et ces Workflows peuvent modifier votre boutique : ajouter des balises aux commandes, envoyer des e-mails, mettre à jour les stocks. En plaçant cette fonctionnalité à un niveau distinct, vous évitez qu'une clé que vous confiez à un script ou à un assistant IA pour les tâches quotidiennes ne déclenche accidentellement vos automatisations. Attribuez par défaut des clés de lecture et ne créez une clé d’exécution que lorsque vous en avez réellement besoin.

URL de base

L'API et le serveur MCP sont hébergés sur un nom d'hôte dédié :

text
https://shopify.workflow-webhooks.app

L'API REST est donc accessible à l'adresse https://shopify.workflow-webhooks.app/api/v1 et le serveur MCP à l'adresse https://shopify.workflow-webhooks.app/api/mcp. La page « Développeurs » affiche ces deux liens, accompagnés d'un bouton « Copier ».

Ce nom d'hôte sert uniquement à /api - l'interface d'administration intégrée reste sur sa propre URL enregistrée : Shopify. Le fait de les séparer garantit que l'adresse que vous collez dans un script, une tâche d'automatisation des processus (CI) ou un client d'IA est stable et indépendante de l'intégration de l'application.

API REST

L'URL de base est indiquée sur la page « Développeurs ». Les principaux points de terminaison sont les suivants :

Méthode Chemin Niveau Objectif
OBTENIR /api/v1 aucun Index API - confirme que l'API est opérationnelle
OBTENIR /api/v1/me lire Vérifiez votre authentification et consultez le niveau de votre clé
OBTENIR /api/v1/webhooks lire Liste des webhooks
PUBLICATION /api/v1/webhooks écrire Créer un webhook
OBTENIR /api/v1/webhooks/:id lire Obtenir un webhook
PUT / PATCH /api/v1/webhooks/:id écrire Mettre à jour un webhook
SUPPRIMER /api/v1/webhooks/:id écrire Supprimer un webhook
PUBLICATION /api/v1/webhooks/:id/test exécuter Lancer un appel de test
OBTENIR /api/v1/history lire Invocations de listes
OBTENIR /api/v1/history/:id lire Récupérez une invocation, avec sa payload
PUBLICATION /api/v1/history/:id/replay exécuter Revoir une invocation passée
OBTENIR /api/v1/stats lire Totaux, taux de réussite, séries quotidiennes
OBTENIR /api/v1/templates lire Modèles de webhooks intégrés

Une vérification rapide pour vous assurer que votre clé fonctionne :

bash
curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"
json
{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

Serveur MCP

Le serveur MCP permet à un assistant IA (Claude, Cursor, VS Code, Gemini CLI et autres) d'interagir avec vos webhooks au cours d'une conversation. Sur la page « Développeurs », l'onglet « MCP » affiche l'URL du serveur ainsi qu'une commande de connexion prête à être copiée pour chaque client, avec votre clé déjà insérée.

Ces outils correspondent aux points de terminaison REST, et leur ensemble dépend du niveau de votre clé : une clé en lecture seule n'a même pas accès aux outils permettant de créer, de supprimer ou de déclencher des webhooks. L'authentification et le traitement des données s'effectuent entièrement côté serveur.

Comment vos données sont-elles protégées ?

Il y a deux choses à savoir avant d'utiliser un outil d'automatisation ou un assistant IA avec cette API.

Le jeton d'authentification de votre webhook n'est jamais accessible. Le jeton ou la clé de signature que vous définissez pour un webhook ne peut en aucun cas être récupéré via l'API ou le MCP. Les réponses vous indiquent uniquement si un jeton est défini (hasToken), mais jamais sa valeur. Vous pouvez en définir un nouveau ; vous ne pouvez en aucun cas récupérer l'ancien.

Les données à caractère personnel contenues dans les payloads sont masquées. Les payloads des webhooks proviennent de systèmes externes et contiennent souvent des informations relatives aux clients. Avant qu’une charge utile d’invocation ne quitte le serveur, les valeurs pouvant ressembler à des données à caractère personnel sont remplacées par *** : adresses e-mail, numéros de téléphone, numéros de carte bancaire et champs portant le nom d’une personne (customerName, shippingAddress et autres). Les en-têtes de requête sont nettoyés de la même manière que le fait l’écran d’historique de l’application.

Ce masquage est minutieux, mais ne constitue pas une garantie. Il s'applique aux noms de champs et aux modèles de valeurs ; par conséquent, les données personnelles contenues dans un champ de texte libre (une note, un commentaire, le corps d'un message) peuvent tout de même être divulguées. Considérez que les réponses de l'API sont susceptibles de contenir des données de clients et stockez-les en conséquence.

Les tests et les relectures n'utilisent pas votre quota. Les appels que vous effectuez via l'API sont enregistrés en tant que tests ; ils ne sont donc pas pris en compte dans le quota mensuel de votre forfait. Les relectures ne sont pas non plus prises en compte, car l'appel d'origine l'a déjà été.

Prochaines étapes

Limites de débit

L'API REST et le serveur MCP partagent un budget commun par clé API.

  • 300 requêtes par 60 secondes et par clé, dans une fenêtre fixe.
  • Les appels de niveau « Execute » disposent d’un deuxième budget, plus restreint, de 60 par heure. Ils utilisent les deux, de sorte qu’une série d’exécutions entame également le quota partagé. Pour cette application, cela signifie l’appel de test d’un webhook et la relecture d’une entrée d’historique, deux opérations qui exécutent réellement vos workflows dShopify Flow.
  • C'est identique pour tous les forfaits. Votre forfait comptabilise les invocations, et non les appels API ; par conséquent, le passage à un forfait supérieur n'entraîne pas d'augmentation de ces chiffres.
  • Si la réponse est un code HTTP 429, veuillez patienter puis réessayer, de préférence en utilisant un délai d'attente exponentiel.
  • Si notre cache est temporairement indisponible, le limiteur se désactive plutôt que de bloquer votre intégration.

The incoming webhooks are not limited in their throughput

Il convient de le préciser, car c'est la question qui nous est le plus souvent posée : nous ne limitons pas le débit des webhooks entrants. Nous les transmettons dès leur réception, quel que soit le rythme de transmission de votre système source : il n'y a aucune limite par seconde ou par minute de notre côté.

La seule limite est **le quota de 30 jours **prévu par votre forfait. Une fois ce quota épuisé, les appels supplémentaires ne sont plus traités jusqu'à ce que la période soit renouvelée ou que vous passiez à un forfait supérieur. Au-delà de cela, ce sont les limites d'Shopify qui s'appliquent : Shopify Flow dispose de ses propres limites d'exécution, et la taille du payload du déclencheur est plafonnée à 50 Ko.

Shopify

Il s'agit des limites imposées par Shopify concernant les API d'Shopify, et non des nôtres. Elles s'appliquent à ce que cette application (et vos workflows) peuvent faire du côté de Shopify, et vous pourriez les atteindre sur une boutique de grande envergure, même si vous restez largement en deçà de nos propres limites.

  • La taille des tableaux d'entrée est limitée à 250 éléments pour toutes les API d'Shopify. Toute requête comportant un tableau plus grand est rejetée.
  • La pagination s'arrête à 25 000 objets. Les décomptes sont exacts jusqu'à 25 000 ; au-delà, la commande Shopify renvoie 25001, ce qui signifie « plus de 25 000 ». Si vous souhaitez aller plus loin, appliquez d'abord un filtre.
  • L'API d'Shopify GraphQL est facturée en fonction du coût calculé des requêtes, exprimé en points par seconde, et le plafond dépend du forfait d' de la boutique :
Shopify forfait Points par seconde
Standard 100
Avancé 200
Et en plus 1 000
Entreprise (composants commerciaux) 2000

L'API de la boutique en ligne n'est soumise à aucune limitation de débit.

Tous les détails : Shopify Limites de débit de l'API