Comment connecter Square à Shopify Flow
Square envoie un Webhook pour les paiements, les commandes, les remboursements, les clients et les modifications de stock sur l'ensemble de ses produits de point de vente et en ligne. « Workflow Webhooks » transforme cet appel en un Déclencheur « **Shopify Flow **», afin que votre boutique puisse y réagir : attribuer une balise à un client, ajouter une note à une 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 : Square envoie les données, Workflow Webhooks les reçoit et les vérifie, Shopify Flow les traite. La signature HMAC de Square est vérifiée à chaque requête, de sorte que seul Square puisse déclencher votre workflow.
Ce que vous pouvez construire
- Identifiez un client Shopify ayant effectué un achat dans votre magasin physique via Square.
- Ajoutez une note concernant un client lorsqu’un remboursement Square est effectué, afin que l’assistance dispose d’une vue d’ensemble de la situation.
- Envoyez un e-mail au personnel lorsque le stock Square d'une référence partagée passe en dessous d'un seuil défini.
Exemples d'événements à envoyer : payment.created, refund.updated, customer.created, inventory.count.updated.
Avant de commencer
- Workflow Webhooks installé sur votre boutique Shopify.
- Shopify Flow installée, disponible gratuitement sur l'App Store d'Shopify.
- Un compte Square disposant des autorisations 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
Square events. - Dans la section « Authentification », sélectionnez « HMAC ».
- Dans la section « Fournisseur de signature », sélectionnez Square. L'application remplit 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 renseignez 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 la page Mappage de la charge utile et variables de flux pour choisir les champs à transmettre à Shopify Flow.
Étape 2 - Ajoutez le point de terminaison dans Square
Dans le tableau de bord des développeurs Square, ouvrez la section « Webhooks » de votre application, ajoutez un abonnement avec l'URL que vous avez copiée, puis copiez la clé de signature.
Comment trouver votre code secret de connexion à Square
La clé de signature de l'abonnement au webhook (Tableau de bord des développeurs Square -> Webhooks).
La documentation de Square sur les signatures de webhooks () contient la formulation exacte et des captures d'écran spécifiques à votre compte.
Collez ce secret dans le champ « Secret » du webhook sur Workflow Webhooks, puis enregistrez. À partir de ce moment-là, chaque livraison Square sera vérifiée avant d'arriver dans Shopify Flow.
Ce que cette vérification permet de contrôler
| Quoi ? | Valeur |
|---|---|
| En-tête de signature | x-square-hmacsha256-signature |
| Emplacement de la signature | La valeur complète de l'en-tête |
| Ce qui est signé | {url}{body} |
| Signature | HMAC-SHA256, encodé en base64 |
| Horodatage | Non utilisé par cet expéditeur |
| Protection contre la relecture | Aucune - cet expéditeur ne signe pas l'horodatage ; par conséquent, toute signature valide reste valable |
| Le secret | À utiliser sous forme de texte brut. Collez-le exactement tel qu’il apparaît chez l’expéditeur. |
Dans la payload signée, {body} correspond au corps brut de la requête, octet par octet, et {url} correspond à l'URL de ce webhook.
Toute requête qui ne respecte 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
- 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 test depuis Square (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 basée sur l'identifiant du webhook afin de limiter ce workflow à Square uniquement. L'identifiant est indiqué sur la page dédiée aux webhooks.
- Ajoutez vos actions : balisez 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 Square. Dans « Workflow Webhooks » -> « Historique », 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 le fonctionnement de l'outil de test 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 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 Square 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 Square sélectionné, que le secret est renseigné et que Square 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 parvenue à destination. Vérifiez à nouveau l'URL dans Square et consultez le journal de transmission de Square 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.
The workflow runs for inappropriate events▾
Chaque webhook de votre boutique déclenche le même déclencheur Shopify Flow. Ajoutez une condition portant sur l'identifiant du webhook comme première étape du workflow, ou affinez les événements que vous envoyez depuis Square.
Connexes
- Vérification des webhooks signés - tous les prestataires 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 Square effectue une nouvelle tentative de livraison ?
- Historique et dépannage - le journal de chaque requête, avec possibilité de relecture.