Bekræftelse af signerede webhooks
Mange tjenester underskriver de webhooks, de sender, så modtageren kan bekræfte, at en anmodning rent faktisk stammer fra dem og ikke er blevet ændret undervejs. Indstil en webhook-autentificering til HMAC, så appen kontrollerer signaturen, inden noget når frem til Shopify Flow. En anmodning, der ikke består kontrollen, afvises med fejlkoden 401, og der udføres aldrig en arbejdsgang.
Der er to måder at konfigurere det på: Vælg afsenderen fra listen, eller beskriv, hvordan den underskriver.
Indbyggede udbydere
Vælg udbyderen under »Signaturudbyder«, og indsæt dennes signeringsnøgle. Appen kontrollerer derefter, at udbyderen overholder de angivne krav - den korrekte header, kodning, signeret indhold og replay-vindue - så der er ikke andet, der skal konfigureres. Hver udbyder har sin egen installationsvejledning, lige fra oprettelse af endpointet til opbygning af »Shopify Flow«-arbejdsgangen.
Hver vejledning angiver præcist, hvad appen kontrollerer for den pågældende afsender, og hvor man kan finde dennes signeringsnøgle.
Brugerdefineret signatur: enhver anden afsender
Hvis din afsender ikke er på listen, skal du vælge »Brugerdefineret signatur« og beskrive, hvordan den signerer. Din udbyders dokumentation vil indeholde en linje, der lyder omtrent således:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Den ene linje dækker alle felter:
| Indstilling | Fra eksemplet | Hvad det betyder |
|---|---|---|
| Signaturhoved | X-Acme-Signature |
Overskriften med underskriften |
| Algoritme | hmac_sha256 |
SHA-256, SHA-1 eller SHA-512 |
| Kodning | hex |
hex, base64 eller base64url |
| Signeret payload | {timestamp}.{body} |
Den nøjagtige tekst, der blev underskrevet |
| Tidspunkt | en overskrift som f.eks. X-Acme-Timestamp |
Hvor værdien af »timestamp« bevæger sig hen |
| Tolerance for gentagelse | 300 sekunder | Afvis anmodninger, der er ældre end dette |
Den signerede payload
Skriv, hvad afsenderen underskriver, ved hjælp af disse pladsholdere:
| Pladsholder | Bliver |
|---|---|
{body} |
Den ubehandlede anmodningstekst, byte for byte. Påkrævet. |
{timestamp} |
Tidstemplet fra overskriften eller signaturoverskriften |
{url} |
Denne webhooks URL, som du indtastede hos afsenderen |
{header:name} |
Værdien af en anden anmodningsheader |
Almindelige former: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Brug »Start fra en udbyder« til at kopiere et tæt match og kun ændre det, der adskiller sig.
Hvor underskriften er placeret
- Almindeligt: Værdien i overskriften er signaturen, eventuelt efterfulgt af et præfiks, som du selv vælger, f.eks.
sha256=ellerv1,. - Nøgle = værdi: Overskriften indeholder par som f.eks.
t=1700000000,v1=abc.... Angiv navnet på den nøgle, der indeholder signaturen (v1), eventuelt navnet på den nøgle, der indeholder tidsstemplet (t), samt om parrene er adskilt med,eller;.
Hvis en overskrift indeholder flere signaturer adskilt af mellemrum - hvilket nogle afsendere gør, når man skifter hemmelighed - accepteres enhver signatur, der stemmer overens.
Hemmeligheden
Normalt indsætter man nøglen, præcis som afsenderen viser den. Nogle afsendere angiver en base64-kodet nøgle med et præfiks, f.eks. whsec_...: Vælg »base64-kodet«, og indtast det præfiks, der skal fjernes.
Testning inden idriftsættelse
Signaturtesteren er placeret under indstillingerne og fungerer, selvom ændringerne ikke er gemt.
- Indsæt brødteksten og overskrifterne fra en reel anmodning, og tryk på »Verificer«. Du får vist hvert enkelt trin - overskrift fundet, signatur læst, tidsstempel inden for intervallet, payload opbygget, signaturer sammenlignet - samt den nøjagtige tekst, der blev signeret, så en uoverensstemmelse viser dig, hvor der gik noget galt, i stedet for blot at vise en besked om »ugyldig signatur«.
- Funktionen »Generer et gyldigt eksempel« genererer korrekt signerede headere og en »
curl«, der er klar til brug, baseret på dine nuværende indstillinger. Hvis denne anmodning accepteres, er din konfiguration konsistent fra ende til ende.
Testeren starter aldrig en arbejdsgang, skriver intet til historikken og tæller ikke med i din plan.
Signaturen stemmer ikke overens. Hvad skal jeg tjekke?▾
I denne rækkefølge: hemmeligheden (den mest almindelige årsag, herunder et ekstra mellemrum eller den forkerte nøgle til miljøet), den signerede payload (et manglende . eller : mellem tidsstemplet og brødteksten), kodningen (hex vs. base64) og om noget mellem afsenderen og appen har ændret brødteksten. Signaturer dækker de rå bytes, så en proxy, der omformaterer JSON, ødelægger dem.
Anmodningerne mislykkes med fejlmeddelelsen »tidsstempel uden for tolerancegrænsen«▾
Afsenderens ur er forkert indstillet, anmodningen blev forsinket eller forsøgt igen med et gammelt tidsstempel, eller tidsstempel-enheden er forkert. Kontroller, om din afsender bruger sekunder, millisekunder eller en ISO-dato.
Min afsender skal først gennemføre en verifikationshåndtryk▾
Nogle tjenester (Zoom, Dropbox, Asana, Trello, Notion) sender en verifikationsforespørgsel, som endpointet skal besvare, før de leverer begivenheder - hver på sin egen måde. Af den grund tilbydes de ikke som »one-click«-udbydere. Kontakt supporten med navnet på din afsender, hvis du har brug for en af disse tjenester.
Er signaturen gemt et eller andet sted?▾
Nej. Signaturoverskrifter skjules i historikken og i Live Request Inspector, da en signatur kan gentages inden for dens tolerancevindue.