Gecertificeerde webhooks verifiëren
Veel diensten voorzien de webhooks die zij verzenden van een handtekening, zodat de ontvanger kan vaststellen dat een verzoek daadwerkelijk van hen afkomstig is en onderweg niet is gewijzigd. Stel de authenticatie van een webhook in op HMAC, waarna de app die handtekening controleert voordat er iets Shopify Flow bereikt. Een verzoek dat deze controle niet doorstaat, wordt afgewezen met de foutmelding 401 en er wordt nooit een workflow uitgevoerd.
Er zijn twee manieren om dit in te stellen: kies de afzender uit de lijst, of geef aan hoe deze ondertekent.
Ingebouwde providers
Kies de provider onder ‘Signature provider’ en plak de ondertekeningssleutel ervan. De app controleert vervolgens of de provider aan de vereisten voldoet - de juiste header, codering, ondertekende inhoud en replay-venster - zodat u verder niets meer hoeft te configureren. Elke provider beschikt over een eigen installatiehandleiding, van het aanmaken van het eindpunt tot het opzetten van de Shopify Flow-workflow.
In elke handleiding wordt precies vermeld wat de app bij die afzender controleert en waar het ondertekeningsgeheim te vinden is.
Aangepaste handtekening: elke andere afzender
Indien uw afzender niet in de lijst voorkomt, kiest u ‘Aangepaste handtekening’ en beschrijft u hoe deze wordt ondertekend. In de documentatie van uw provider staat een regel zoals:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Die ene regel geeft voor elk veld een antwoord:
| Setting | Uit het voorbeeld | Wat dit betekent |
|---|---|---|
| Handtekeningkoptekst | X-Acme-Signature |
De koptekst met de handtekening |
| Algoritme | hmac_sha256 |
SHA-256, SHA-1 of SHA-512 |
| Codering | hex |
hex, base64 of base64url |
| Ondertekende payload | {timestamp}.{body} |
De exacte tekst die werd ondertekend |
| Tijdstempel | een koptekst zoals X-Acme-Timestamp |
Waar de waarde van timestamp naartoe gaat |
| Herhalingstolerantie | 300 seconden | Verzoeken die ouder zijn dan dit, afwijzen |
De ondertekende payload
Schrijf op wat de afzender ondertekent met behulp van deze plaatshouders:
| Plaatshouder | Wordt |
|---|---|
{body} |
De onbewerkte inhoud van het verzoek, byte voor byte. Verplicht. |
{timestamp} |
De tijdstempel uit de header of de handtekeningheader |
{url} |
De URL van deze webhook, zoals u deze bij de afzender hebt ingevoerd |
{header:name} |
De waarde van een andere verzoekheader |
Veelvoorkomende vormen: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Gebruik de optie ‘Start bij een aanbieder’ om een sterk overeenkomende variant te kopiëren en pas alleen de verschillen aan.
Waar de handtekening staat
- Eenvoudig gezegd: de waarde van de header is de handtekening, eventueel gevolgd door een door u gekozen voorvoegsel, zoals
sha256=ofv1,. - Sleutel = waarde: de header bevat paren zoals
t=1700000000,v1=abc.... Geef de sleutel op die de handtekening bevat (v1), eventueel de sleutel die de tijdstempel bevat (t), en of de paren worden gescheiden door,of;.
Indien een header meerdere handtekeningen bevat die door spaties van elkaar worden gescheiden - wat sommige afzenders doen wanneer u een geheim afwisselt - wordt elke handtekening die overeenkomt, geaccepteerd.
Het geheim
Meestal plakt u de geheime code precies zoals de afzender deze weergeeft. Sommige afzenders verstrekken een in Base64-code gecodeerde sleutel met een voorvoegsel, zoals whsec_...: kies dan voor ‘Base64-gecodeerd’ en voer het voorvoegsel in dat u wilt verwijderen.
Testen voordat u live gaat
De handtekeningcontrole bevindt zich onder de instellingen en werkt ook bij niet-opgeslagen wijzigingen.
- Plak de hoofdtekst en de headers van een echt verzoek en klik op ‘Verifiëren’. U krijgt elke stap te zien - header gevonden, handtekening gelezen, tijdstempel binnen het bereik, payload samengesteld, handtekeningen vergeleken - en de exacte tekst die is ondertekend, zodat u bij een afwijking precies kunt zien waar het mis is gegaan, in plaats van alleen de melding ‘ongeldige handtekening’ te krijgen.
- Met de optie ‘Een geldig voorbeeld genereren’ worden correct ondertekende headers en een uitvoerbare
curlvoor uw huidige instellingen gegenereerd. Indien dat verzoek wordt geaccepteerd, is uw configuratie van begin tot eind consistent.
De tester start nooit een workflow, schrijft niets naar de geschiedenis en telt niet mee voor uw abonnement.
De handtekening komt niet overeen. Wat moet ik controleren?▾
In deze volgorde: het geheim (de meest voorkomende oorzaak, zoals een extra spatie of de verkeerde sleutel van de omgeving), de ondertekende payload (een ontbrekend . of : tussen de tijdstempel en de body), de codering (hex versus base64) en of er iets tussen de afzender en de app de body heeft gewijzigd. Handtekeningen hebben betrekking op de ruwe bytes, dus een proxy die JSON opnieuw opmaakt, maakt ze ongeldig.
Verzoeken mislukken met de foutmelding "tijdstempel buiten de tolerantie"▾
De klok van de afzender loopt niet synchroon, het verzoek is vertraagd of opnieuw verzonden met een verouderde tijdstempel, of de eenheid van de tijdstempel is onjuist. Controleer of uw afzender seconden, milliseconden of een ISO-datum gebruikt.
Mijn afzender heeft eerst een verificatieprocedure nodig▾
Sommige diensten (Zoom, Dropbox, Asana, Trello, Notion) sturen een verificatieverzoek waarop het eindpunt moet reageren voordat zij gebeurtenissen doorgeven, elk op hun eigen manier. Om die reden worden zij niet aangeboden als ‘één-klik’-providers. Neem contact op met de support en vermeld de naam van uw afzender als u een van deze diensten nodig hebt.
Wordt de handtekening ergens opgeslagen?▾
Nee. Handtekeningkopteksten worden in de Geschiedenis en in de Live Request Inspector verborgen, omdat een handtekening binnen het tolerantievenster kan worden herhaald.