Workflow WebhooksWorkflow Webhooks

So verbinden Sie Square mit Shopify Flow

Square sendet einen Webhook für Zahlungen, Bestellungen, Rückerstattungen, Kunden und Änderungen am Inventar über seine Kassensysteme und Online-Produkte hinweg. „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 - Square sendet, Workflow Webhooks empfängt und überprüft, Shopify Flow führt die Aktion aus -, wobei bei jeder Anfrage die HMAC-Signatur von Square überprüft wird, sodass ausschließlich Square Ihren Workflow initiieren kann.

Was Sie bauen können

  • Tag einen Kunden von Shopify, der in Ihrem Ladengeschäft über Square eingekauft hat.
  • Fügen Sie bei einer Rückerstattung über Square eine Notiz für den Kunden hinzu, damit der Support den vollständigen Sachverhalt nachvollziehen kann.
  • Senden Sie eine E-Mail an die Mitarbeiter, sobald das Inventar bei Square für eine gemeinsam genutzte SKU unter einen Schwellenwert fällt.

Typische Ereignisse, die gesendet werden sollten: payment.created, refund.updated, customer.created, inventory.count.updated.

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 bei Square mit der Berechtigung, Webhooks zu erstellen.

Schritt 1 - Erstellen Sie den Webhook unter Workflow Webhooks

  1. Öffnen Sie „Workflow Webhooks“** -> „Webhooks“ -> „Webhook erstellen“** und geben Sie ihm einen Namen, den Sie in Shopify Flow wiedererkennen, beispielsweise Square events.
  2. Wählen Sie unter „Authentifizierung“ die Option „HMAC“ aus.
  3. Wählen Sie unter „Signaturanbieter“ die Option „Square“ aus. Die App füllt die Felder „Header“, „Algorithmus“, „signierte Payload“ und „Replay-Fenster“ automatisch für Sie aus - es sind keine weiteren Einstellungen erforderlich.
  4. 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 in Square hinzu

Öffnen Sie im Square Developer Dashboard den Abschnitt „Webhooks“ Ihrer Anwendung, fügen Sie ein Abonnement mit der kopierten URL hinzu und kopieren Sie den Signaturschlüssel.

So finden Sie Ihr Square-Signaturgeheimnis

Der Signaturschlüssel des Webhook-Abonnements (Square Developer Dashboard -> Webhooks).

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

Fügen Sie diesen Schlüssel in das Feld „Secret“ des Webhooks unter Workflow Webhooks ein und speichern Sie die Eingabe. Ab diesem Zeitpunkt wird jede Square-Zahlung überprüft, bevor sie Shopify Flow erreicht.

Was hier überprüft wird

Was Wert
Signaturzeile x-square-hmacsha256-signature
Wo sich die Unterschrift befindet Der gesamte Wert der Kopfzeile
Was wurde unterzeichnet? {url}{body}
Unterschrift HMAC-SHA256, Base64-kodiert
Zeitstempel Wird von diesem Absender nicht verwendet
Wiedergabeschutz Keine - dieser Absender signiert keinen Zeitstempel, daher bleibt jede gültige Signatur gültig
Das Geheimnis Wird als Klartext verwendet. Fügen Sie den Text genau so ein, wie er vom Absender angegeben wird.

In der signierten Payload entspricht {body} dem Rohtext des Anfrage-Hauptteils, Byte für Byte, und {url} ist die URL dieses Webhooks.

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

Schritt 3 - Erstellen Sie den Shopify Flow-Workflow

  1. Erstellen Sie in „Shopify Flow“ einen Workflow und wählen Sie den Trigger „Workflow Webhooks“ aus.
  2. Klicken Sie auf „Ereignisse aufzeichnen“ und senden Sie anschließend ein Testereignis über Square (oder verwenden Sie die Funktion „Test senden“ unter Workflow Webhooks), damit Shopify Flow die Struktur Ihrer Daten erkennt.
  3. Jeder Webhook, den Sie besitzen, 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 Square zu beschränken. Die ID wird auf der Webhook-Seite angezeigt.
  4. Fügen Sie Ihre Aktionen hinzu - taggen Sie einen Kunden, fügen Sie eine Notiz hinzu, versenden Sie eine interne E-Mail, aktualisieren Sie ein Metafeld.
Shopify Flow
Wählen Sie unter Shopify Flow die Option „Select a trigger“ aus, öffnen Sie Workflow Webhooks und wählen Sie „Webhook Trigger“ aus.
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 anhand 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 - Führen Sie einen End-to-End-Test durch

Lösen Sie ein echtes Ereignis in Square aus. Unter „Workflow Webhooks“ → „History“ sollten Sie den Aufruf mit dem Status „Success“ sehen. Sollte die Signatur fehlerhaft gewesen sein, erhalten Sie stattdessen einen fehlgeschlagenen Eintrag mit der entsprechenden Begründung. 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 aufgezeichnet
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 Square und der App den Hauptteil umschreibt. Signaturen beziehen sich auf die Rohbytes, 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 „Square“ ausgewählt ist, ob das Geheimnis eingegeben wurde und ob Square die Daten genau an die URL sendet, 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 Square noch einmal und sehen Sie sich das eigene Zustellungsprotokoll von Square an, um die erhaltene Antwort einzusehen. Ein 404 bedeutet, dass der Webhook falsch ist oder gelöscht wurde; ein 429 bedeutet, dass Sie das Aufruflimit Ihres Tarifs überschritten haben - siehe Pläne und Nutzung.

Der Workflow wird für die falschen Ereignisse 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 von Square senden.

Verwandte Themen