Vérification des webhooks signés
De nombreux services signent les Webhooks qu’ils envoient, afin que le destinataire puisse vérifier qu’une requête provient bien d’eux et qu’elle n’a pas été altérée en cours de route. Définissez l’authentification d’un Webhook sur HMAC et l’application vérifiera cette signature avant que quoi que ce soit n’atteigne Shopify Flow. Une requête qui échoue à cette vérification est rejetée avec le message 401 et ne déclenche jamais de workflow.
Il existe deux façons de procéder : sélectionner l'expéditeur dans la liste ou décrire son mode de signature.
Fournisseurs intégrés
Sélectionnez le fournisseur dans la section «** Fournisseur de signature** » et collez sa clé de signature. L'application vérifie ensuite que le fournisseur respecte les spécifications requises (en-tête correct, encodage, contenu signé et fenêtre de relecture) ; il n'y a donc rien d'autre à configurer. Chaque fournisseur dispose de son propre guide de configuration, allant de la création du point de terminaison à la mise en place du workflow Shopify Flow.
Chaque guide indique précisément ce que l'application vérifie pour cet expéditeur et où trouver sa clé de signature.
Signature personnalisée : tout autre expéditeur
Si votre expéditeur ne figure pas dans la liste, sélectionnez « Signature personnalisée » et décrivez comment il signe. La documentation de votre fournisseur contiendra une ligne du type :
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Cette seule ligne répond à toutes les questions :
| Contexte | D'après l'exemple | Ce que cela signifie |
|---|---|---|
| En-tête de signature | X-Acme-Signature |
L'en-tête comportant la signature |
| Algorithme | hmac_sha256 |
SHA-256, SHA-1 ou SHA-512 |
| Encodage | hex |
hex, base64 ou base64url |
| Payload signé | {timestamp}.{body} |
Le texte exact qui a été signé |
| Horodatage | un en-tête tel que X-Acme-Timestamp |
Où passe la valeur de timestamp ? |
| Tolérance de relecture | 300 secondes | Refuser les demandes antérieures à cette date |
The signed payload
Veuillez indiquer ce que l'expéditeur signe à l'aide de ces espaces réservés :
| Espace réservé | Devient |
|---|---|
{body} |
Le corps brut de la requête, octet par octet. Obligatoire. |
{timestamp} |
L'horodatage figurant dans l'en-tête ou dans l'en-tête de signature |
{url} |
L'URL de ce webhook, telle que vous l'avez saisie chez l'expéditeur |
{header:name} |
La valeur d'un autre en-tête de requête |
Formes courantes : {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Utilisez l’option « Partir d’un fournisseur » pour copier une correspondance proche et ne modifier que les éléments qui diffèrent.
Emplacement de la signature
- Simple : la valeur d'en-tête correspond à la signature, éventuellement suivie d'un préfixe de votre choix, tel que
sha256=ouv1,. - Clé = valeur : l'en-tête contient des paires telles que
t=1700000000,v1=abc.... Indiquez le nom de la clé contenant la signature (v1), éventuellement celui de la clé contenant l'horodatage (t), ainsi que le format de séparation des paires :,ou;.
Si un en-tête contient plusieurs signatures séparées par des espaces - ce que font certains expéditeurs lorsque vous changez de clé - , n'importe laquelle d'entre elles qui correspond est acceptée.
Le secret
En général, vous collez la clé telle qu'elle est affichée par l'expéditeur. Certains expéditeurs fournissent une clé encodée en Base64 avec un préfixe, par exemple whsec_... : sélectionnez « encodée en Base64 » et saisissez le préfixe à supprimer.
Tests avant la mise en production
Le testeur de signature se trouve sous les paramètres et fonctionne même si les modifications n'ont pas été enregistrées.
- Collez le corps et les en-têtes d'une requête réelle, puis cliquez sur « Vérifier ». Vous obtenez chaque étape - en-tête détecté, signature lue, horodatage dans la plage autorisée, payload construit, signatures comparées - ainsi que le texte exact qui a été signé ; ainsi, en cas de non-correspondance, vous voyez précisément où le problème s'est produit, plutôt que de simplement recevoir un message indiquant « signature non valide ».
- La génération d'un exemple valide permet d'obtenir des en-têtes correctement signés et une requête
curlprête à être exécutée, en fonction de vos paramètres actuels. Si cette requête est acceptée, cela signifie que votre configuration est cohérente de bout en bout.
Le testeur ne lance jamais de workflow, n'enregistre rien dans l'historique et n'est pas pris en compte dans votre forfait.
La signature ne correspond pas. Que dois-je vérifier ?▾
Dans cet ordre : le secret (cause la plus courante, notamment un espace superflu ou une clé d’environnement erronée), la charge utile signée (. ou : manquant entre l’horodatage et le corps du message), l’encodage (hexadécimal ou base64), et la présence éventuelle d’une modification du corps du message entre l’expéditeur et l’application. Les signatures portent sur les octets bruts ; par conséquent, un proxy qui reformate le JSON les invalide.
Les requêtes échouent avec le message « horodatage hors tolérance »▾
L'horloge de l'expéditeur est déréglée, la requête a été retardée ou réessayée avec un horodatage obsolète, ou bien l'unité d'horodatage est incorrecte. Vérifiez si votre expéditeur utilise des secondes, des millisecondes ou une date ISO.
Mon expéditeur a d'abord besoin d'une procédure de vérification▾
Certains services (Zoom, Dropbox, Asana, Trello, Notion) envoient une demande de vérification à laquelle le point de terminaison doit répondre avant de transmettre le moindre événement, chacun à sa manière. C'est pour cette raison qu'ils ne sont pas proposés sous forme de fournisseurs « en un clic ». Veuillez contacter l'assistance en indiquant le nom de votre expéditeur si vous avez besoin de l'un d'entre eux.
La signature est-elle enregistrée quelque part ?▾
Non. Les en-têtes de signature sont masqués dans l'historique et dans l'inspecteur de requêtes en temps réel, car une signature peut être reproduite dans les limites de sa fenêtre de tolérance.