So verbinden Sie Standard-Webhooks mit Shopify Flow

Q: Die Signatur stimmt nicht überein

In dieser Reihenfolge: das Geheimnis (die häufigste Ursache - ein zusätzliches Leerzeichen oder ein Schlüssel aus der falschen Umgebung), ob der Absender das Geheimnis eines anderen Endpunkts verwendet und ob irgendetwas zwischen den Standard-Webhooks und der App den Hauptteil umformuliert . Signaturen beziehen sich auf die Rohdaten, sodass ein Proxy, der JSON neu formatiert, diese ungültig macht. Der Signatur-Tester auf der Webhook-Seite zeigt den genauen Text an, der signiert wurde.

„Standard Webhooks“ ist eine offene Spezifikation zur Signierung von Webhooks, die von OpenAI, Supabase Auth Hooks und einer stetig wachsenden Zahl von Diensten genutzt wird. Eine einzige Voreinstellung deckt alle diese Dienste ab. „Workflow Webhooks“ wandelt diesen Aufruf in einen „Shopify Flow“-Trigger um, sodass Ihr Shop darauf reagieren kann: einen Kunden kennzeichnen, eine Bestellnotiz hinzufügen, eine interne E-Mail versenden, ein Metafeld aktualisieren - alles, was Shopify Flow leisten kann.

Dieser Leitfaden beschreibt den gesamten Ablauf - Standard Webhooks sendet, Workflow Webhooks empfängt und überprüft, Shopify Flow führt die Aktion aus -, wobei bei jeder Anfrage die HMAC-Signatur von Standard Webhooks überprüft wird, sodass ausschließlich Standard Webhooks Ihren Workflow auslösen kann.

Was Sie bauen können

Nehmen Sie einen OpenAI-Webhook - einen abgeschlossenen Batch-Auftrag oder eine vollständige Antwort - und lassen Sie Shopify Flow das Ergebnis in Ihrem Shop umsetzen.
Reagieren Sie auf einen Supabase-Auth-Hook, sodass bei einer Registrierung in Ihrer eigenen App der entsprechende Kunde in Shopify gekennzeichnet wird.
Empfangen Sie Daten von jedem Dienst, der die Spezifikation von standardwebhooks.com erfüllt, ohne eine benutzerdefinierte Signatur konfigurieren zu müssen.

Typische zu sendende Ereignisse: alle Ereignisse, die der sendende Dienst definiert.

Dieselbe Voreinstellung überprüft zudem Webhooks von OpenAI und Supabase Auth Hooks.

Bevor Sie beginnen

Workflow Webhooks in Ihrem Shopify-Shop installiert.
Shopify Flow installiert, die kostenlos im App Store unter Shopify erhältlich ist.
Ein Konto für Standard-Webhooks mit der Berechtigung zum Erstellen von Webhooks.

Schritt 1 - Erstellen Sie den Webhook unter Workflow Webhooks

Öffnen Sie „Workflow Webhooks“** -> „Webhooks“ -> „Webhook erstellen“** und vergeben Sie einen Namen, den Sie in Shopify Flow wiedererkennen, beispielsweise Standard Webhooks events.
Wählen Sie unter „Authentifizierung“ die Option „HMAC“ aus.
Wählen Sie unter „Signaturanbieter“ die Option** „Standard-Webhooks“** aus. Die App füllt die Felder „Header“, „Algorithmus“, „signiertes Payload“ und „Wiederholungsfenster“ automatisch für Sie aus - es sind keine weiteren Einstellungen erforderlich.
Lassen Sie das Feld „Secret“ vorerst leer und klicken Sie auf „Speichern“. Kopieren Sie die auf der Seite angezeigte URL des Webhooks.

Informationen zu den anderen Authentifizierungsmodi finden Sie unter Authentifizierung, und unter Zuordnung der Payload-Daten und Flow-Variablen erfahren Sie, welche Felder an Shopify Flow übermittelt werden.

Schritt 2 - Fügen Sie den Endpunkt unter „Standard-Webhooks“ hinzu

Fügen Sie die URL als Endpunkt im sendenden Dienst hinzu und kopieren Sie anschließend den dort angezeigten Signaturschlüssel (er beginnt mit whsec_).

So finden Sie Ihr Signaturgeheimnis für Standard-Webhooks

Das Signaturgeheimnis, das mit „whsec_“ beginnt. Fügen Sie es vollständig ein; falls es als „v1,whsec_...“ (Supabase) angezeigt wird, lassen Sie das führende „v1,“ weg.

In der Dokumentation von Standard Webhooks zu Webhook-Signaturen unter finden Sie den genauen Wortlaut sowie Screenshots für Ihr Konto.

Fügen Sie dieses Geheimnis in das Feld „Secret“ des Webhooks unter Workflow Webhooks ein und speichern Sie es. Ab diesem Zeitpunkt wird jede Zustellung über Standard-Webhooks überprüft, bevor sie Shopify Flow erreicht.

Was hier überprüft wird

Was	Wert
Signaturzeile	`webhook-signature`
Wo sich die Unterschrift befindet	Der Wert des Header-Elements nach dem Präfix `v1,`
Was wurde unterzeichnet?	`{header:webhook-id}.{timestamp}.{body}`
Unterschrift	HMAC-SHA256, Base64-kodiert
Zeitstempel	Der Header `webhook-timestamp` als Unix-Sekunden
Wiedergabeschutz	Anfragen, deren signierter Zeitstempel mehr als 5 Minuten vom aktuellen Zeitpunkt entfernt ist, werden abgelehnt
Das Geheimnis	Vor der Verwendung wird der Text Base64-dekodiert. Das vorangestellte `whsec_` wird vor der Dekodierung entfernt. Fügen Sie den Text genau so ein, wie er vom Absender angezeigt wird.

In der signierten Payload entspricht {body} dem Rohtext des Anfrage-Hauptteils, Byte für Byte, {timestamp} dem oben genannten Zeitstempel und {header:webhook-id} dem Anfrage-Header webhook-id.

Eine Anfrage, die eine dieser Bedingungen nicht erfüllt, wird mit dem Fehler 401 abgelehnt, unter Hintergrund und Fehlerbehebung protokolliert und löst niemals einen Workflow aus.

Schritt 3 - Erstellen Sie den Workflow Shopify Flow

Erstellen Sie in „Shopify Flow“ einen Workflow und wählen Sie den Trigger „Workflow Webhooks“ aus.
Klicken Sie auf „Ereignisse aufzeichnen“ und senden Sie anschließend ein Testereignis über „Standard-Webhooks“ (oder verwenden Sie die Option „Test senden“ unter Workflow Webhooks), damit Shopify Flow die Struktur Ihrer Daten erkennt.
Jeder Ihrer Webhooks löst denselben Shopify Flow-Trigger aus. Fügen Sie daher eine erste Bedingung für die Webhook-ID hinzu, um diesen Workflow ausschließlich auf Standard-Webhooks zu beschränken. Die ID wird auf der Webhook-Seite angezeigt.
Fügen Sie Ihre Aktionen hinzu - markieren Sie einen Kunden, fügen Sie eine Notiz hinzu, versenden Sie eine interne E-Mail, aktualisieren Sie ein Metafeld.

Eine Shopify Flow-Bedingung: Die Webhook-ID entspricht der ID eines Webhooks — Der erste Schritt jedes Workflows: eine Bedingung bezüglich der Webhook-ID, damit der Workflow nur für diesen Webhook ausgeführt wird.

Der fertige Workflow: Webhook-Trigger, eine Bedingung basierend auf der Webhook-ID, anschließend „Interne E-Mail senden“ im „True“-Zweig — Der fertige Workflow: Trigger, Bedingung anhand der Webhook-ID, anschließend Ihre Aktion im „True“-Zweig.

Schritt 4 - Testen Sie das System von Anfang bis Ende

Lösen Sie ein echtes Ereignis in „Standard Webhooks“ aus. Unter „Workflow Webhooks“ → „History“ sollten Sie den Aufruf mit dem Status „Success“ sehen. Falls die Signatur fehlerhaft war, erhalten Sie stattdessen einen Eintrag mit dem Status „Failed“ und dem entsprechenden Grund; unter Überprüfung signierter Webhooks finden Sie Erläuterungen zum Signatur-Tester, der Ihnen genau anzeigt, welcher Schritt fehlgeschlagen ist.

Ein Aufruf wurde im Protokoll „History“ mit seinen Anforderungsheadern, der Payload, dem Status, der Dauer und den Kennungen aufgeführt — Ein in „History“ übermittelter Vorgang: Der Status „Erfolgreich“ bedeutet, dass Shopify Flow diesen akzeptiert hat.

Die Signatur stimmt nicht überein▾

In dieser Reihenfolge: das Geheimnis (die häufigste Ursache - ein zusätzliches Leerzeichen oder ein Schlüssel aus der falschen Umgebung), ob der Absender das Geheimnis eines anderen Endpunkts verwendet und ob irgendetwas zwischen den Standard-Webhooks und der App den Hauptteil umformuliert. Signaturen beziehen sich auf die Rohdaten, sodass ein Proxy, der JSON neu formatiert, diese ungültig macht. Der Signatur-Tester auf der Webhook-Seite zeigt den genauen Text an, der signiert wurde.

Bei jeder Anfrage erhalte ich den Fehlercode 401▾

Bitte überprüfen Sie, ob die Authentifizierung des Webhooks auf „HMAC“ eingestellt ist und der Anbieter „Standard Webhooks“ ausgewählt ist, ob das Geheimnis eingegeben wurde und ob „Standard Webhooks“ die URL genau so anruft, wie sie in der App angezeigt wird - einschließlich des Codes am Ende.

Im Verlauf wird nichts angezeigt▾

Die Anfrage ist nie angekommen. Überprüfen Sie die URL in „Standard Webhooks“ noch einmal und sehen Sie sich im Zustellungsprotokoll von „Standard Webhooks“ die erhaltene Antwort an. Ein 404 bedeutet, dass der Webhook falsch ist oder gelöscht wurde; ein 429 bedeutet, dass Sie das Aufruflimit Ihres Plans überschritten haben - siehe Pläne und Nutzung.

Der Workflow wird bei falschen Ereignissen ausgeführt▾

Jeder Webhook in Ihrem Shop löst denselben Shopify Flow-Trigger aus. Fügen Sie als ersten Schritt des Workflows eine Bedingung für die Webhook-ID hinzu oder schränken Sie die Ereignisse ein, die Sie über Standard-Webhooks senden.

Anfragen schlagen mit der Fehlermeldung „Zeitstempel außerhalb der Toleranz“ fehl▾

Standard Webhooks versieht die Ereignisse mit einem Zeitstempel, und die App lehnt alle Ereignisse ab, die älter als 5 Minuten sind. Dies ist in der Regel auf ein Zeitproblem auf der sendenden Seite zurückzuführen oder darauf, dass Standard Webhooks die Zustellung erst viel später mit dem ursprünglichen Zeitstempel erneut versucht hat. Wiederholungsversuche derselben ursprünglichen Anfrage können nicht akzeptiert werden; bitten Sie Standard Webhooks, ein neues Ereignis zu senden.