Überprüfung signierter Webhooks
Viele Dienste signieren die von ihnen gesendeten Webhooks, damit der Empfänger nachweisen kann, dass eine Anfrage tatsächlich von ihnen stammt und unterwegs nicht verändert wurde. Wenn Sie die Authentifizierung eines Webhooks auf „HMAC“ einstellen, überprüft die App diese Signatur, bevor die Anfrage Shopify Flow erreicht. Eine Anfrage, die diese Überprüfung nicht besteht, wird mit dem Fehler 401 abgelehnt, und es wird kein Workflow ausgeführt.
Es gibt zwei Möglichkeiten, dies einzurichten: Wählen Sie Ihren Absender aus der Liste aus oder beschreiben Sie, wie er signiert.
Integrierte Anbieter
Wählen Sie unter „Signaturanbieter“ den gewünschten Anbieter aus und fügen Sie dessen Signaturschlüssel ein. Die App überprüft anschließend die vom Anbieter dokumentierte Vorgehensweise - den korrekten Header, die Kodierung, den signierten Inhalt und das Replay-Fenster -, sodass keine weiteren Konfigurationen erforderlich sind. Jeder Anbieter verfügt über eine eigene Einrichtungsanleitung, die von der Erstellung des Endpunkts bis zum Aufbau des Shopify Flow-Workflows reicht.
In jeder Anleitung wird genau aufgeführt, was die App bei diesem Absender überprüft und wo sich dessen Signaturschlüssel befindet.
Individuelle Signatur: jeder andere Absender
Sollte Ihr Absender nicht in der Liste aufgeführt sein, wählen Sie „Benutzerdefinierte Signatur“ und beschreiben Sie, wie die Signatur erfolgt. In der Dokumentation Ihres Anbieters finden Sie einen Eintrag wie beispielsweise:
X-Acme-Signature = hex(hmac_sha256(secret, timestamp + "." + body))
Diese eine Zeile füllt alle Felder aus:
| Einstellung | Aus dem Beispiel | Was das bedeutet |
|---|---|---|
| Signaturzeile | X-Acme-Signature |
Die Kopfzeile, die die Unterschrift enthält |
| Algorithmus | hmac_sha256 |
SHA-256, SHA-1 oder SHA-512 |
| Kodierung | hex |
Hex, Base64 oder Base64URL |
| Signierte Payload | {timestamp}.{body} |
Der genaue Wortlaut des unterzeichneten Dokuments |
| Zeitstempel | eine Kopfzeile wie beispielsweise X-Acme-Timestamp |
Wohin der Wert von timestamp weitergeleitet wird |
| Wiederholungstoleranz | 300 Sekunden | Anträge, die älter sind als dies, sind abzulehnen |
Die signierte Payload
Geben Sie mithilfe dieser Platzhalter ein, was der Absender unterschreibt:
| Platzhalter | Wird zu |
|---|---|
{body} |
Der Rohtext des Anfrage-Hauptteils, Byte für Byte. Erforderlich. |
{timestamp} |
Der Zeitstempel aus dem Header oder dem Signatur-Header |
{url} |
Die URL dieses Webhooks, wie Sie sie beim Absender eingegeben haben |
{header:name} |
Der Wert eines weiteren Request-Headers |
Gängige Formate: {body}, {timestamp}.{body}, {timestamp}{body}, v0:{timestamp}:{body}, {header:webhook-id}.{timestamp}.{body}. Verwenden Sie die Option „Von einem Anbieter ausgehen“, um eine ähnliche Vorlage zu kopieren und nur die abweichenden Stellen zu ändern.
Wo sich die Unterschrift befindet
- Einfach ausgedrückt: Der Wert des Headers ist die Signatur, optional gefolgt von einem von Ihnen festgelegten Präfix, wie beispielsweise
sha256=oderv1,. - Schlüssel = Wert: Der Header enthält Paare wie beispielsweise
t=1700000000,v1=abc.... Geben Sie den Namen des Schlüssels an, der die Signatur enthält (v1), optional den Namen des Schlüssels, der den Zeitstempel enthält (t), sowie an, ob die Paare durch,oder;getrennt sind.
Wenn ein Header mehrere durch Leerzeichen getrennte Signaturen enthält - was manche Absender tun, während Sie ein Geheimnis rotieren -, wird jede Signatur akzeptiert, die übereinstimmt.
Das Geheimnis
In der Regel fügen Sie den Schlüssel so ein, wie er vom Absender angezeigt wird. Manche Absender geben einen Base64-kodierten Schlüssel mit einem Präfix an, beispielsweise whsec_...: Wählen Sie „Base64-kodiert“ aus und geben Sie das Präfix ein, das entfernt werden soll.
Testen vor der Inbetriebnahme
Der Signatur-Tester befindet sich unterhalb der Einstellungen und funktioniert auch bei nicht gespeicherten Änderungen.
- Fügen Sie den Textkörper und die Header einer echten Anfrage ein und klicken Sie auf „Überprüfen“. Sie erhalten eine detaillierte Übersicht über jeden einzelnen Schritt - Header gefunden, Signatur gelesen, Zeitstempel im zulässigen Bereich, Payload erstellt, Signaturen verglichen - sowie den genauen Text, der signiert wurde. So zeigt Ihnen eine Nichtübereinstimmung genau, wo der Fehler liegt, anstatt nur die bloße Meldung „ungültige Signatur“ anzuzeigen.
- Wenn Sie ein gültiges Beispiel generieren, werden korrekt signierte Header und ein lauffertiges
curlfür Ihre aktuellen Einstellungen erstellt. Wird diese Anfrage akzeptiert, ist Ihre Konfiguration durchgängig konsistent.
Der Tester startet niemals einen Workflow, schreibt keine Einträge in den Verlauf und wird nicht auf Ihren Plan angerechnet.
Die Signatur stimmt nicht überein. Was sollte ich überprüfen?▾
In dieser Reihenfolge: das Geheimnis (die häufigste Ursache, einschließlich eines zusätzlichen Leerzeichens oder des falschen Schlüssels für die Umgebung), die signierte Payload (ein fehlendes . oder : zwischen Zeitstempel und Hauptteil), die Kodierung (Hex vs. Base64) und die Frage, ob etwas zwischen dem Absender und der App den Hauptteil verändert hat. Da sich die Signaturen auf die Rohbytes beziehen, werden sie durch einen Proxy, der JSON neu formatiert, ungültig.
Anfragen schlagen mit der Fehlermeldung „Zeitstempel außerhalb der Toleranz“ fehl▾
Die Uhr des Absenders ist falsch eingestellt, die Anfrage wurde verzögert oder mit einem veralteten Zeitstempel erneut gesendet, oder die Einheit des Zeitstempels ist falsch. Überprüfen Sie, ob Ihr Absender Sekunden, Millisekunden oder ein ISO-Datum verwendet.
Mein Absender benötigt zunächst einen Verifizierungs-Handshake▾
Einige Dienste (Zoom, Dropbox, Asana, Trello, Notion) senden eine Verifizierungsanfrage, die der Endpunkt beantworten muss, bevor sie Ereignisse übermitteln - jeder auf seine eigene Weise. Aus diesem Grund werden sie nicht als Ein-Klick-Anbieter angeboten. Wenden Sie sich bitte unter Angabe des Namens Ihres Absenders an den Support, falls Sie einen dieser Dienste benötigen.
Wird die Signatur irgendwo gespeichert?▾
Nein. Signatur-Header werden im Verlauf und im Live-Request-Inspector ausgeblendet, da eine Signatur innerhalb ihres Toleranzfensters erneut gesendet werden kann.