Comment connecter des webhooks standard à Shopify Flow
« Standard Webhooks » est une spécification ouverte permettant de signer des webhooks, utilisée par OpenAI, Supabase Auth Hooks et un nombre croissant de services. Un seul préréglage suffit pour tous ces services. « Workflow Webhooks » transforme cet appel en un déclencheur « **Shopify Flow **», afin que votre boutique puisse y réagir : marquer un client, ajouter une note de commande, envoyer un e-mail interne, mettre à jour un métachamp… tout ce qu’Shopify Flow peut faire.
Ce guide décrit l'ensemble du processus : les envois effectués par Standard Webhooks, la réception et la vérification par Workflow Webhooks, puis l'exécution par Shopify Flow. La signature HMAC de Standard Webhooks est vérifiée à chaque requête, de sorte que seul Standard Webhooks puisse déclencher votre workflow.
Ce que vous pouvez créer
- Prenez un webhook OpenAI - une tâche par lots terminée ou une réponse complète - et demandez à Shopify Flow d'agir en fonction du résultat dans votre boutique.
- Réagissez à un hook d'authentification Supabase, afin qu'une inscription dans votre propre application associe le client correspondant sur Shopify.
- Recevez des notifications de n'importe quel service respectant la spécification standardwebhooks.com sans avoir à configurer de signature personnalisée.
Événements types à envoyer : tout événement défini par le service émetteur.
Ce même préréglage vérifie également les webhooks provenant d'OpenAI et de Supabase Auth Hooks.
Avant de commencer
- Workflow Webhooks installé sur votre boutique Shopify.
- Shopify Flow installée, disponible gratuitement sur la Boutique d'Shopify.
- Un compte « Standard Webhooks » disposant des droits nécessaires pour créer des webhooks.
Étape 1 - Créez le webhook sur Workflow Webhooks
- Accédez à Workflow Webhooks -> Webhooks -> Créer un webhook et attribuez-lui un nom que vous pourrez reconnaître dans Shopify Flow, tel que
Standard Webhooks events. - Dans la section « Authentification », sélectionnez HMAC.
- Dans la section « Fournisseur de signature », sélectionnez « Webhooks standard ». L'application renseigne automatiquement les champs « en-tête », « algorithme », « payload signé » et « fenêtre de relecture » ; vous n'avez rien d'autre à configurer.
- Pour l'instant, ne remplissez pas le champ « Secret » et cliquez sur « Enregistrer ». Copiez l'URL du webhook qui s'affiche 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 choisir les champs à transmettre à Shopify Flow.
Étape 2 - Ajoutez le point de terminaison dans « Standard Webhooks »
Ajoutez l'URL en tant que point de terminaison dans le service d'envoi, puis copiez la clé de signature qui s'affiche (elle commence par whsec_).
Comment trouver votre clé de signature pour les webhooks standard
Le secret de signature commençant par « whsec_ ». Collez-le dans son intégralité ; s'il s'affiche sous la forme « v1,whsec_... » (Supabase), ne tenez pas compte du « v1, » initial.
La documentation de Standard Webhooks consacrée aux signatures de webhooks () contient la formulation exacte 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 transmission via les webhooks Standard est vérifiée avant d'atteindre Shopify Flow.
Ce que cette vérification permet de contrôler
| Quoi ? | Valeur |
|---|---|
| En-tête de signature | webhook-signature |
| Emplacement de la signature | La valeur de l'en-tête, après le préfixe v1, |
| Ce qui est signé | {header:webhook-id}.{timestamp}.{body} |
| Signature | HMAC-SHA256, encodé en base64 |
| Horodatage | L'en-tête webhook-timestamp, exprimé en secondes Unix |
| Protection contre la relecture | Les requêtes dont l'horodatage signé remonte à plus de 5 minutes sont rejetées. |
| Le secret | Décodé en Base64 avant utilisation. Le préfixe whsec_ est supprimé avant le décodage. Collez-le exactement tel qu'il apparaît chez l'expéditeur. |
Dans la charge utile signée, {body} correspond au corps brut de la requête, octet par octet, {timestamp} correspond à l'horodatage mentionné ci-dessus, et {header:webhook-id} correspond à l'en-tête de requête webhook-id.
Toute requête qui ne respecte pas l'une de ces conditions est rejetée avec l'erreur 401, est enregistrée dans Historique et dépannage et ne déclenche jamais de workflow.
Étape 3 - Créer le workflow Shopify Flow
- Dans « Shopify Flow », créez un workflow et sélectionnez le déclencheur « Workflow Webhooks ».
- Cliquez sur « Enregistrer les événements », puis envoyez un événement de test à partir de « Webhooks standard » (ou utilisez l'option « Envoyer un test » dans Workflow Webhooks) afin que Shopify Flow apprenne la structure de vos données.
- Chaque webhook dont vous disposez déclenche le même déclencheur de Shopify Flow ; veuillez donc ajouter une première condition sur l'identifiant du webhook afin de limiter ce workflow aux webhooks standard uniquement. L'identifiant est indiqué sur la page du webhook.
- Ajoutez vos actions : identifiez un client, ajoutez une note, envoyez un e-mail interne, mettez à jour un métachamp.
Étape 4 - Testez-le de bout en bout
Déclenchez un événement réel dans « Standard Webhooks ». Dans « Workflow Webhooks » -> « History », vous devriez voir l'invocation avec le statut « Success ». Si la signature était incorrecte, vous obtiendrez à la place une entrée indiquant un échec avec le motif correspondant, et Vérification des webhooks signés explique le fonctionnement de l'outil de vérification de signature qui vous indique précisément quelle étape a échoué.
La signature ne correspond pas▾
Dans cette commande : le secret (cause la plus fréquente : un espace superflu 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 les webhooks standard 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 des webhooks affiche le texte exact qui a été signé.
Je reçois un code 401 à chaque requête▾
Vérifiez que l'authentification du webhook est configurée sur HMAC avec le fournisseur « Standard Webhooks » sélectionné, que le secret est renseigné et que « Standard Webhooks » envoie les données à 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 « Standard Webhooks » et consultez le journal de livraison de « Standard Webhooks » pour connaître la réponse reçue. Un message 404 indique qu'un webhook est incorrect ou a été supprimé ; un message 429 signifie que vous avez dépassé la limite d'appels de votre forfait - consultez 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 à partir des webhooks standard.
Les requêtes échouent avec le message « horodatage hors tolérance »▾
Standard Webhooks appose un horodatage et l'application rejette tout événement datant de plus de 5 minutes. Il s'agit généralement d'un problème d'horloge du côté de l'expéditeur, ou d'une transmission que Standard Webhooks a réessayé d'envoyer bien plus tard en conservant l'horodatage d'origine. Les tentatives de réenvoi issues de la même requête d'origine ne peuvent pas aboutir ; veuillez demander à Standard Webhooks d'envoyer un nouvel événement.
Connexes
- Vérification des webhooks signés - chaque prestataire que nous vérifions, et comment décrire ceux que nous ne vérifions pas.
- Mappage de la charge utile et variables de flux - extraire les champs appropriés de la payload et les transférer dans Shopify Flow.
- Protection contre les livraisons en double - Que se passe-t-il lorsque les webhooks standard tentent à nouveau d'effectuer une livraison ?
- Historique et dépannage - le journal de chaque requête, avec possibilité de relecture.