Workflow WebhooksWorkflow Webhooks

Comment connecter Sanity à Shopify Flow

Sanity envoie un Webhook alimenté par GROQ chaque fois qu'un contenu correspondant à votre requête est créé, mis à jour ou supprimé. Workflow Webhooks transforme cet appel en un déclencheur « **Shopify Flow **», afin que votre boutique puisse y réagir : associer un client à un produit, ajouter une note de commande, envoyer un e-mail interne, mettre à jour un métachamp… tout ce qu'Shopify Flow permet de faire.

Ce guide décrit l'ensemble du processus : Sanity envoie les données, Workflow Webhooks les reçoit et les vérifie, Shopify Flow effectue les actions, la signature HMAC de Sanity étant vérifiée à chaque requête, de sorte que seul Sanity puisse lancer votre workflow.

Ce que vous pouvez construire

  • Mettez à jour un métachamp Shopify lorsque l'entrée correspondante du CMS est modifiée, afin que la boutique en ligne reste synchronisée.
  • Envoyez un e-mail à votre équipe de merchandising dès qu'une page d'accueil est mise en ligne.
  • Lancez un workflow de mise à jour du cache après la publication d'un contenu.

Exemples d'événements à envoyer : publication d'un document, mise à jour d'un document, suppression d'un document.

Avant de commencer

  • Workflow Webhooks installé sur votre boutique Shopify.
  • Shopify Flow installée, disponible gratuitement sur l’App Store de Shopify.
  • Un compte sur Sanity disposant des autorisations nécessaires pour créer des webhooks.

Étape 1 - Créez le webhook sur Workflow Webhooks

  1. Accédez à Workflow Webhooks -> Webhooks -> Créer un webhook et attribuez-lui un nom que vous pourrez reconnaître dans Shopify Flow, tel que Sanity events.
  2. Dans la section « Authentification », sélectionnez « HMAC ».
  3. Dans la section « Fournisseur de signature », sélectionnez « Sanity ». L'application remplit automatiquement les champs « en-tête », « algorithme », « Payload signé » et « fenêtre de relecture » ; vous n'avez rien d'autre à configurer.
  4. Pour l'instant, ne renseignez pas le champ « secret » et cliquez sur « Enregistrer ». Copiez l'URL du webhook affichée sur la page.

Consultez la page Authentification pour connaître les autres modes d'authentification, et Mappage de la charge utile et variables de flux pour savoir quels champs sont transmis à Shopify Flow.

Étape 2 - Ajoutez le point de terminaison dans Sanity

Dans Sanity, ouvrez API -> Webhooks, créez un webhook alimenté par GROQ à l'aide de l'URL que vous avez copiée, puis définissez le secret.

Comment trouver votre clé secrète de signature Sanity

Le paramètre « Secret » défini sur le webhook géré par GROQ.

La documentation de Sanity consacrée aux signatures de webhooks, disponible à l'adresse, contient le libellé exact et les captures d'écran correspondant à votre compte.

Collez ce secret dans le champ « Secret » du webhook sur Workflow Webhooks, puis enregistrez. À partir de ce moment, chaque envoi Sanity sera vérifié avant d'atteindre Shopify Flow.

Ce que cette vérification permet de vérifier

Quoi ? Valeur
En-tête de signature sanity-webhook-signature
Emplacement de la signature Dans la valeur v1 de cet en-tête, qui contient des paires key=value séparées par des virgules
Ce qui est signé {timestamp}.{body}
Signature HMAC-SHA256, encodé en base64url
Horodatage La valeur t de l'en-tête de signature, exprimée en millisecondes Unix
Protection contre la relecture Aucune - cet expéditeur ne signe pas l'horodatage ; par conséquent, toute signature valide reste valide
Le secret À utiliser sous forme de texte brut. Copiez-collez-le exactement tel que l'expéditeur l'a indiqué.

Dans la charge utile signée, {body} correspond au corps brut de la requête, octet par octet, et {timestamp} correspond à l'horodatage indiqué ci-dessus.

Toute requête qui ne satisfait pas à l'une de ces conditions est rejetée avec le message 401, est enregistrée dans Historique et dépannage et ne déclenche jamais de workflow.

Étape 3 - Créer le workflow Shopify Flow

  1. Dans «Shopify Flow », créez un workflow et sélectionnez le déclencheur «Workflow Webhooks».
  2. Cliquez sur « Enregistrer les événements », puis envoyez un événement de test depuis Sanity (ou utilisez l'option « Envoyer un test » dans Workflow Webhooks) afin que Shopify Flow apprenne la structure de vos données.
  3. Chaque webhook dont vous disposez déclenche le même déclencheur de flux ; ajoutez donc une première condition basée sur l'identifiant du webhook afin de limiter ce workflow à Sanity uniquement. L'identifiant est indiqué sur la page du webhook.
  4. Ajoutez vos actions : identifiez un client, ajoutez une note, envoyez un e-mail interne, mettez à jour un métachamp.
Shopify Flow
Dans Shopify Flow, sélectionnez « Sélectionner un déclencheur », ouvrez Workflow Webhooks et choisissez « Déclencheur Webhook ».
Condition de Shopify Flow : l'identifiant du webhook est identique à celui d'un webhook
La première étape de chaque workflow : une condition liée à l'identifiant du webhook, afin que le workflow ne s'exécute que pour ce webhook.
Le workflow final : déclencheur Webhook, une condition sur l'identifiant du webhook, puis envoi d'un e-mail interne sur la branche « True »
Le workflow final : un déclencheur, une condition basée sur l'identifiant du webhook, puis votre action sur la branche « True ».

Étape 4 - Testez-le de bout en bout

Déclenchez un événement réel dans Sanity. Dans Workflow Webhooks → «History », vous devriez voir l'appel avec le statut « Success ». Si la signature était incorrecte, vous obtiendrez à la place une entrée indiquant un échec avec la raison correspondante ; la page Vérification des webhooks signés explique comment utiliser l'outil de vérification de signature qui vous indique précisément quelle étape a échoué.

Une requête a été enregistrée dans l'historique avec ses en-têtes de requête, sa payload, son statut, sa durée et ses identifiants
Un événement « livré » dans History : le statut « Succès » signifie que l'Shopify Flow l'a accepté.
La signature ne correspond pas▾

Dans cette commande : le secret (cause la plus courante : un espace supplémentaire ou une clé provenant d’un environnement incorrect), le fait que l’expéditeur utilise le secret d’un autre point de terminaison, et le fait que quelque chose entre Sanity et l’application réécrive le corps du message. Les signatures portent sur les octets bruts ; par conséquent, un proxy qui reformate le JSON les invalide. Le testeur de signature disponible sur la page du webhook affiche le texte exact qui a été signé.

Je reçois un code d'erreur 401 à chaque requête▾

Vérifiez que l'authentification du webhook est configurée sur HMAC avec le fournisseur Sanity sélectionné, que le secret est renseigné et que Sanity envoie ses requêtes à l'URL exactement telle qu'elle s'affiche dans l'application, y compris le code à la fin.

Rien n'apparaît dans l'historique▾

La requête n'est jamais arrivée. Vérifiez à nouveau l'URL dans Sanity et consultez le journal de transmission de Sanity pour voir la réponse qu'il a reçue. Un message 404 indique un webhook incorrect ou supprimé, tandis qu'un message 429 signifie que vous avez dépassé la limite d'appels de votre forfait - voir Forfaits et utilisation.

Le workflow s'exécute pour des événements inappropriés▾

Chaque webhook de votre boutique déclenche le même déclencheur Shopify Flow. Ajoutez une condition basée sur l'identifiant du webhook comme première étape du workflow, ou affinez les événements que vous envoyez depuis Sanity.

Connexes