Verifiering av signerade webhooks
Verifiera HMAC-signaturen på inkommande webhooks innan Shopify Flow körs. 22 inbyggda leverantörer eller en anpassad signatur för andra tjänster.
Många tjänster signerar de webhooks de skickar, så att mottagaren kan verifiera att en begäran verkligen kom från dem och inte har ändrats under vägen. Ställ in webhookens autentisering på HMAC så kontrollerar appen signaturen innan något når Shopify Flow. En begäran som inte klarar kontrollen avvisas med 401 och utlöser aldrig ett arbetsflöde.
Det finns två sätt att ställa in det: välj avsändaren från listan eller beskriv hur den signerar.
Inbyggda leverantörer
Välj leverantör under ”Signaturleverantör” och klistra in leverantörens signaturnyckel. Appen kontrollerar sedan att leverantören följer de angivna kraven - rätt rubrik, kodning, signerat innehåll och återuppspelningsfönster - så det finns inget annat att konfigurera. Varje leverantör har sin egen installationsguide, från att skapa slutpunkten till att bygga upp arbetsflödet i Shopify Flow.
I varje guide anges exakt vad appen kontrollerar för den aktuella avsändaren och var man hittar dennes signeringsnyckel.
Anpassad signatur: alla andra avsändare
Om din avsändare inte finns med i listan väljer du ”Anpassad signatur” och beskriver hur signaturen ser ut. I din leverantörs dokumentation finns en rad som lyder ungefär så här:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Den där enda raden täcker alla fält:
| Miljö | Ur exemplet | Vad det innebär |
|---|---|---|
| Signaturrubrik | X-Acme-Signature |
Rubriken med signaturen |
| Algoritm | hmac_sha256 |
SHA-256, SHA-1 eller SHA-512 |
| Kodning | hex |
hex, base64 eller base64url |
| Signerad nyttolast | {timestamp}.{body} |
Den exakta texten som undertecknades |
| Tidsstämpel | en rubrik som till exempel X-Acme-Timestamp |
Vart värdet timestamp skickas |
| Tolerans vid uppspelning | 300 sekunder | Avvisa förfrågningar som är äldre än detta |
Den signerade nyttolasten
Skriv vad avsändaren undertecknar med hjälp av följande platshållare:
| Platshållare | Blir |
|---|---|
{body} |
Den obearbetade begäran, byte för byte. Obligatoriskt. |
{timestamp} |
Tidsstämpeln från rubriken eller signaturrubriken |
{url} |
Denna webhooks URL, så som du angav den hos avsändaren |
{header:name} |
Värdet i en annan begäranrubrik |
Vanliga format: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Använd funktionen ”Starta från en leverantör” för att kopiera en liknande form och ändra endast det som skiljer sig åt.
Var signaturen ska placeras
- Enkelt: värdet i rubriken är signaturen, eventuellt följt av ett prefix som du själv väljer, till exempel
sha256=ellerv1,. - Nyckel = värde: rubriken innehåller par av typen
t=1700000000,v1=abc.... Ange namnet på nyckeln som innehåller signaturen (v1), eventuellt namnet på nyckeln som innehåller tidsstämpeln (t), samt om paren ska separeras med,eller;.
Om en rubrik innehåller flera signaturer åtskilda av mellanslag - vilket vissa avsändare gör när man roterar en hemlig nyckel - godtas vilken som helst som stämmer överens.
Hemligheten
Vanligtvis klistrar du in hemligheten precis som avsändaren visar den. Vissa avsändare tillhandahåller en Base64-kodad nyckel med ett prefix, till exempel whsec_...: välj ”Base64-kodad” och ange vilket prefix som ska tas bort.
Testa innan du går live
Signaturtestaren finns under inställningarna och fungerar även med ändringar som inte har sparats.
- Klistra in huvudtexten och rubrikerna från en riktig begäran och klicka på ”Verifiera”. Du får se varje steg - rubrik hittad, signatur avläst, tidsstämpel inom intervallet, nyttolast skapad, signaturer jämförda - samt den exakta texten som signerades, så att en avvikelse visar var felet uppstod istället för bara ett enkelt ”ogiltig signatur”.
- Med funktionen ”Generera ett giltigt exempel” skapas korrekt signerade rubriker och ett körklart
curl-kommando anpassat efter dina aktuella inställningar. Om den begäran godkänns är din konfiguration konsekvent från början till slut.
Testaren startar aldrig ett arbetsflöde, skriver ingenting till historiken och räknas inte in i ditt abonnemang.
Signaturen stämmer inte. Vad ska jag kontrollera?
I följande ordning: hemligheten (den vanligaste orsaken, till exempel ett extra mellanslag eller fel nyckel för miljön), den signerade nyttolasten (en saknad . eller : mellan tidsstämpeln och huvudtexten), kodningen (hex vs base64) och om något mellan avsändaren och appen har ändrat huvudtexten. Signaturerna täcker de råa byte, så en proxy som omformaterar JSON bryter dem.
Förfrågningarna misslyckas med felmeddelandet ”tidsstämpel utanför toleransgränsen”
Avsändarens klocka är felinställd, begäran försenades eller skickades på nytt med en gammal tidsstämpel, eller så är tidsstämpelns enhet felaktig. Kontrollera om din avsändare använder sekunder, millisekunder eller ett ISO-datum.
Min avsändare behöver först genomföra en verifieringsprocess
Vissa tjänster (Zoom, Dropbox, Asana, Trello, Notion) skickar en verifieringsförfrågan som slutpunkten måste besvara innan de levererar några händelser, var och en på sitt eget sätt. Av den anledningen erbjuds de inte som ”ett-klick”-leverantörer. Kontakta supporten och ange namnet på din avsändare om du behöver någon av dem.
Lagrar man signaturen någonstans?
Nej. Signaturhuvuden döljs i historiken och i Live Request Inspector, eftersom en signatur kan återges inom sitt toleransfönster.