Entwickler-API und MCP

Alles, was Sie in der App verwalten, können Sie auch über Ihren eigenen Code oder über einen KI-Assistenten verwalten. Workflow Webhooks stellt zwei Schnittstellen bereit: eine REST-API und einen MCP-Server. Beide finden Sie auf der Entwicklerseite.

API-Schlüssel

Beide Oberflächen authentifizieren sich über einen API-Schlüssel. Erstellen Sie auf der Entwicklerseite unter „API-Schlüssel“ einen Schlüssel und wählen Sie dessen Zugriffsebene aus:

• Nur-Lesezugriff - Webhooks auflisten, Aufrufverlauf und Statistiken einsehen.
• Lesen und Schreiben - sowie Erstellen, Aktualisieren und Löschen von Webhooks.
• Lesen, schreiben und ausführen - außerdem können Sie einen Testaufruf starten oder einen früheren Aufruf wiederholen.

Der vollständige Schlüssel wird einmalig bei der Erstellung angezeigt. Kopieren Sie ihn dann und bewahren Sie ihn sicher auf; Sie können ihn danach nicht mehr einsehen. Schlüssel werden in gehashtem Format gespeichert, niemals im Klartext, und Sie können einen Schlüssel jederzeit widerrufen.

Senden Sie den Schlüssel bei jeder Anfrage als „Bearer“-Token:

Authorization: Bearer fwk_your_key_here

Warum die Ausführung eine eigene Ebene darstellt

Das Auslösen eines Webhooks führt tatsächlich Ihre Shopify Flow-Workflows aus, und diese Workflows können Änderungen an Ihrem Shop bewirken - beispielsweise das Versenden von Etiketten für Bestellungen, das Versenden von E-Mails oder die Aktualisierung des Inventars. Indem Sie dies auf einer separaten Ebene halten, stellen Sie sicher, dass ein Schlüssel, den Sie einem Skript oder einem KI-Assistenten für alltägliche Aufgaben übergeben, Ihre Automatisierungen nicht versehentlich auslösen kann. Vergeben Sie standardmäßig Leseschlüssel und erstellen Sie einen Ausführungsschlüssel nur dann, wenn Sie diesen tatsächlich benötigen.

Basis-URL

Die API und der MCP-Server werden über einen eigenen Hostnamen bereitgestellt:

https://shopify.workflow-webhooks.app

Die REST-API ist also unter https://shopify.workflow-webhooks.app/api/v1 zu finden und der MCP-Server unter https://shopify.workflow-webhooks.app/api/mcp. Auf der Entwickler-Seite werden beide mit einer Schaltfläche zum Kopieren angezeigt.

Dieser Hostname dient ausschließlich der Bereitstellung von /api - die eingebettete Admin-Benutzeroberfläche verbleibt unter ihrer eigenen, bei Shopify registrierten URL. Durch diese Trennung bleibt die Adresse, die Sie in ein Skript, einen CI-Job oder einen KI-Client einfügen, stabil und unabhängig von der Einbettung der App.

REST-API

Die Basis-URL wird auf der Entwicklerseite angezeigt. Die wichtigsten Endpunkte:

Verfahren	Pfad	Stufe	Zweck
GET	/api/v1	keine	API-Index - bestätigt, dass die API verfügbar ist
GET	/api/v1/me	lesen	Überprüfen Sie die Authentifizierung und sehen Sie sich die Stufe Ihres Schlüssels an
GET	/api/v1/webhooks	lesen	Webhooks auflisten
BEITRAG	/api/v1/webhooks	schreiben	Webhook erstellen
GET	/api/v1/webhooks/:id	lesen	Einen Webhook einrichten
PUT / PATCH	/api/v1/webhooks/:id	schreiben	Einen Webhook aktualisieren
LÖSCHEN	/api/v1/webhooks/:id	schreiben	Einen Webhook löschen
BEITRAG	/api/v1/webhooks/:id/test	ausführen	Führen Sie einen Testaufruf durch
GET	/api/v1/history	lesen	Listenaufrufe
GET	/api/v1/history/:id	lesen	Rufen Sie einen Aufruf mit seiner Payload ab
BEITRAG	/api/v1/history/:id/replay	ausführen	Einen früheren Aufruf wiederholen
GET	/api/v1/stats	lesen	Gesamtzahlen, Erfolgsquote, tägliche Reihen
GET	/api/v1/templates	lesen	Integrierte Webhook-Vorlagen

Eine kurze Überprüfung, ob Ihr Schlüssel funktioniert:

curl https://shopify.workflow-webhooks.app/api/v1/me \
  -H "Authorization: Bearer fwk_your_key_here"

{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }

MCP-Server

Der MCP-Server ermöglicht es einem KI-Assistenten (Claude, Cursor, VS Code, Gemini CLI und anderen), im Rahmen einer Unterhaltung mit Ihren Webhooks zu arbeiten. Auf der Seite „Entwickler“ werden auf der Registerkarte „MCP“ die Server-URL sowie ein kopierfertiger Verbindungsbefehl für jeden Client angezeigt, in den Ihr Schlüssel bereits eingefügt ist.

Die Tools spiegeln die REST-Endpunkte wider, und der Funktionsumfang richtet sich nach der Berechtigungsstufe Ihres Schlüssels: Ein schreibgeschützter Schlüssel hat nicht einmal Zugriff auf die Tools, mit denen Webhooks erstellt, gelöscht oder ausgelöst werden. Die gesamte Authentifizierung und Datenverarbeitung erfolgt serverseitig.

Wie Ihre Daten geschützt werden

Bevor Sie eine Automatisierung oder einen KI-Assistenten auf diese API anwenden, sollten Sie zwei Dinge beachten.

Das Authentifizierungstoken Ihres Webhooks ist niemals einsehbar. Das Token oder der Signaturschlüssel, den Sie für einen Webhook festgelegt haben, kann auf keiner Ebene über die API oder das MCP abgerufen werden. Die Antworten geben lediglich Auskunft darüber, ob ein Token festgelegt ist (hasToken), niemals jedoch über dessen Wert. Sie können ein neues Token festlegen; das alte können Sie jedoch niemals abrufen.

Personenbezogene Daten in Payloads werden maskiert. Webhook-Payloads stammen aus externen Systemen und enthalten häufig Daten von Kunden. Bevor eine Aufruf-Payload den Server verlässt, werden Werte, die wie personenbezogene Daten aussehen, durch *** ersetzt: E-Mail-Adressen, Telefonnummern, Kartennummern sowie Felder, die nach einer Person benannt sind (z. B. customerName, shippingAddress und Ähnliches). Anfrage-Header werden auf dieselbe Weise bereinigt wie auf dem Verlaufsbildschirm der App.

Diese Maskierung erfolgt sorgfältig, stellt jedoch keine Garantie dar. Sie wirkt sich auf Feldnamen und Wertmuster aus, sodass personenbezogene Daten, die sich in einem Freitextfeld befinden - beispielsweise eine Notiz, ein Kommentar oder der Textkörper einer Nachricht -, dennoch durchgelassen werden können. Behandeln Sie API-Antworten so, als enthielten sie möglicherweise Kundendaten, und speichern Sie sie entsprechend.

Tests und Wiederholungen werden nicht auf Ihr Kontingent angerechnet. Aufrufe, die Sie über die API auslösen, werden als Tests aufgezeichnet und zählen daher nicht auf das monatliche Kontingent Ihres Plans an. Auch Wiederholungen werden nicht angerechnet, da der ursprüngliche Aufruf bereits berücksichtigt wurde.

Nächste Schritte

• Einführung in Workflow Webhooks - wie Webhooks und die Zuordnung von Payloads funktionieren.

Ratenbegrenzungen

Die REST-API und der MCP-Server teilen sich ein Budget pro API-Schlüssel.

• 300 Anfragen pro 60 Sekunden pro Schlüssel, als festes Zeitfenster.
• Aufrufe auf Ausführungsebene erhalten ein zweites, knapperes Kontingent von 60 pro Stunde. Da beide Kontingente verbraucht werden, greift eine Häufung von Ausführungen auch auf das gemeinsame Kontingent zurück. Für diese App bedeutet dies das Testaufrufen eines Webhooks und das Wiedergeben eines Verlaufseintrags - beides führt tatsächlich Ihre Shopify Flow-Workflows aus.
• Dies gilt für alle Pläne gleichermaßen. Ihr Plan misst die Anzahl der Aufrufe, nicht die der API-Aufrufe; daher führt ein Upgrade nicht zu einem Anstieg dieser Zahlen.
• Es wird der HTTP-Status 429 zurückgegeben. Bitte warten Sie und versuchen Sie es erneut, idealerweise mit exponentiellem Backoff.
• Sollte unser Cache vorübergehend nicht verfügbar sein, fällt der Begrenzer in den „Fail-Open“-Modus zurück, anstatt Ihre Integration zu blockieren.

Für eingehende Webhooks gilt keine Ratenbegrenzung

Um es klar zu sagen, denn dies ist die Frage, die uns am häufigsten gestellt wird: Wir drosseln eingehende Webhook-Übermittlungen nicht. Wir leiten sie so schnell weiter, wie sie eintreffen, ganz gleich, in welchen Spitzen Ihr Quellsystem sie erzeugt - es gibt auf unserer Seite keine Begrenzung pro Sekunde oder pro Minute.

Die einzige Obergrenze ist das 30-Tage-Kontingent Ihres Tarifs. Sobald dieses aufgebraucht ist, werden weitere Aufrufe nicht mehr verarbeitet, bis das Zeitfenster erneut beginnt oder Sie ein Upgrade vornehmen. Darüber hinaus gelten die von Shopify festgelegten Beschränkungen: Shopify Flow hat eigene Ausführungsbeschränkungen, und die Größe der Trigger-Payload ist auf 50 KB begrenzt.

Shopify

Dies sind die von Shopify festgelegten Beschränkungen für die APIs von Shopify, nicht unsere eigenen. Sie gelten für die Funktionen, die diese App (und Ihre Workflows) auf der Seite von Shopify ausführen können, und es kann vorkommen, dass Sie bei einem großen Shop an diese Grenzen stoßen, selbst wenn Sie unsere eigenen Beschränkungen bei weitem nicht ausschöpfen.

• Die Anzahl der Elemente in Eingabe-Arrays ist bei allen Shopify-APIs auf 250 begrenzt. Eine Anfrage mit einem Array, das diese Grenze überschreitet, wird abgelehnt.
• Die Paginierung endet bei 25.000 Objekten. Die Zählwerte sind bis zu 25.000 korrekt; darüber hinaus gibt Shopify den Wert 25001 zurück, was „mehr als 25.000“ bedeutet. Wenn Sie tiefer in die Daten einsteigen möchten, filtern Sie diese bitte zunächst.
• Die GraphQL-Admin-API wird anhand der berechneten Abfragekosten in Punkten pro Sekunde abgerechnet, wobei die Obergrenze vom Shopify-Plan des Shops abhängt:

Shopify Plan	Punkte pro Sekunde
Standard	100
Fortgeschritten	200
Außerdem	1000
Enterprise (Handelskomponenten)	2000

Für die Storefront-API gilt keine Ratenbegrenzung.

Ausführliche Informationen: Shopify API-Ratenbegrenzungen