Entwickler-API, MCP, GitHub und Trigger-Simulation

Sie können Ihre Trigger überprüfen, sie aktivieren oder deaktivieren, den Ereignisverlauf einsehen und einen Trigger aus Ihrem eigenen Code oder über einen KI-Assistenten simulieren. Workflow Trigger Extensions stellt eine REST-API und einen MCP-Server bereit und lässt sich** mit einem GitHub-Repository verbinden**, sodass Ihr benutzerdefinierter Trigger-Code unter Versionskontrolle steht. Alle drei Komponenten werden auf der Entwicklerseite verwaltet.

Simulation eines Triggers

Das Testen eines Flow-Workflows bedeutet normalerweise, den tatsächlichen Vorgang in Ihrem Shop auszuführen - ein Produkt bearbeiten, eine Bestellung aufgeben, auf eine Umfrage warten. Durch die Simulation entfällt diese Wartezeit: Wählen Sie einen Trigger aus, ordnen Sie ihn einer Ressource zu, und er wird ausgelöst, als ob das tatsächliche Ereignis gerade stattgefunden hätte.

Zwei Möglichkeiten, dies zu tun:

• Öffnen Sie in der App ein beliebiges Ereignis im Ereignisverlauf und wählen Sie erneut „Simulieren“ aus. Dadurch wird genau dieses Ereignis erneut ausgelöst.
• Über die API oder MCP, anhand einer Ressourcen-ID oder eines vergangenen Ereignisses.

Die Simulation ist bewusst originalgetreu. Es wird keine verkürzte Payload erstellt - sie durchläuft dieselbe Pipeline wie ein echter Webhook von Shopify, sodass Ihr Workflow genau das erhält, was er auch in der Produktionsumgebung erhalten würde.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'

Ein Testlauf validiert den Trigger, löst das Thema auf und zeigt Ihnen die Payload an - ohne dass dabei etwas ausgelöst wird. Entfernen Sie dryRun, um den Trigger tatsächlich auszulösen. Sie können auch {"fromHistoryId":"456"} übergeben, um ein bereits stattgefundenes Ereignis erneut auszulösen, anstatt ein neues zu erstellen.

Trigger, die über eine Abfrage statt über einen Webhook gesteuert werden, können nicht simuliert werden; sie werden in der Triggerliste als simulatable: false angezeigt.

API-Schlüssel

Erstellen Sie auf der Seite „Entwickler“ einen Schlüssel und wählen Sie dessen Zugriffsebene aus:

• Nur-Lesezugriff - Auflisten von Triggern und deren Status, Abrufen des Ereignisverlaufs, der Statistiken und der Berechtigungen.
• Lesen und Schreiben - sowie das Ein- und Ausschalten von Triggern.
• Lesen, schreiben und ausführen - außerdem können Sie Trigger simulieren und benutzerdefinierten Trigger-Code testen.

Der vollständige Schlüssel wird einmalig bei der Erstellung angezeigt. Schlüssel werden in gehashtem Zustand gespeichert und können jederzeit widerrufen werden. Senden Sie ihn als „Bearer“-Token:

Authorization: Bearer ftk_your_key_here

Die Simulation befindet sich aus dem oben genannten Grund auf einer eigenen Ebene: Sie führt Ihre Automatisierungen tatsächlich aus, sodass ein Schlüssel, der für alltägliche Lesevorgänge verwendet wird, diese nicht auslösen kann.

REST-API

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/triggers	lesen	Jeder Trigger mit seinem Status für Ihren Shop
GET	/api/v1/triggers/:handle	lesen	Ein Trigger im Detail
PUT	/api/v1/triggers/:handle	schreiben	Einen Trigger ein- oder ausschalten
PUT	/api/v1/triggers	schreiben	Mehrere Geräte in einem Vorgang ein- oder ausschalten
BEITRAG	/api/v1/triggers/:handle/simulate	ausführen	Einen Trigger simulieren
GET	/api/v1/triggers/custom	lesen	Ihre eigenen benutzerdefinierten Trigger mit dem dazugehörigen Code
GET	/api/v1/triggers/custom/:handle/test	lesen	Das Ereignis „Erfasste Stichprobe“ für einen benutzerdefinierten Trigger
BEITRAG	/api/v1/triggers/custom/:handle/test	ausführen	Benutzerdefinierten Trigger-Code ausführen, ohne zu speichern oder auszulösen
GET	/api/v1/history	lesen	Trigger-Ereignisse auflisten
GET	/api/v1/history/:id	lesen	Ein Ereignis mit seiner Payload abrufen
GET	/api/v1/stats	lesen	Gesamtzahlen, Erfolgsquote, Aufschlüsselung nach Status
GET	/api/v1/permissions	lesen	Welche Datenberechtigungen Sie erteilt haben und welche Funktionen dadurch jeweils freigeschaltet werden

GET /api/v1/triggers Dies ist eine nützliche Hilfe bei der Einrichtung: Für jeden Trigger wird angegeben, welche Berechtigung erforderlich ist, ob diese Berechtigung erteilt wurde, ob der Trigger aktiviert ist und an welcher Stelle in der App er verwaltet werden kann.

Trigger ein- und ausschalten

PUT wird anstelle von PATCH verwendet, da der Aufruf idempotent ist - eine erneute Ausführung nach Ablauf einer Zeitüberschreitung kann keine doppelte Anwendung bewirken, was von Bedeutung ist, wenn ein Assistent die API steuert.

curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Mit „Enable“ wird niemals eine Berechtigung erteilt. Sollte der Trigger eine Berechtigung benötigen, die Sie noch nicht erteilt haben, wird der Aufruf dennoch erfolgreich ausgeführt, und es wird Ihnen genau mitgeteilt, was fehlt und wo Sie die Berechtigung erteilen müssen:

{
  "enabled": true,
  "scopeGranted": false,
  "missingScopeLabels": ["Order Data Access"],
  "permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
  "warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}

Über diesen Link wird die Seite „Berechtigungen“ geöffnet, auf der die gewünschte Karte bereits angezeigt wird.

Fügen Sie "sync": true hinzu, um zusätzlich eine Datensynchronisierung zu starten, sodass der Trigger auch bei bereits vorhandenen Datensätzen funktioniert und nicht nur bei solchen, die ab sofort angelegt werden.

Um mehrere Elemente gleichzeitig umzuschalten, akzeptiert PUT /api/v1/triggers eine explizite Liste oder eine gesamte Kategorie:

{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }

GitHub verbinden

Auf der Seite „Entwickler“ können Sie über die Registerkarte „Verbindungen“ ein GitHub-Repository für Ihren Benutzerdefinierte Trigger-Code verknüpfen. Änderungen werden in einem Pull-Request zur Überprüfung bereitgestellt, Sie können sehen, wer welche Änderungen vorgenommen hat, und Sie können eine Transformation rückgängig machen, die nicht mehr funktioniert.

Durch das Verbinden wird unsere GitHub-App in dem von Ihnen ausgewählten Konto installiert. Sie legen fest, auf welche Repositorys die App Zugriff hat, und können diesen Zugriff jederzeit über GitHub widerrufen. Wenn Sie ein Repository auswählen, werden alle bereits vorhandenen benutzerdefinierten Trigger sofort darin gespeichert, sodass die App von Anfang an mit dem Repository synchronisiert ist und nicht erst im Laufe der Zeit nach und nach ergänzt wird.

Was Sie tun	Was geschieht
Erstellen, bearbeiten oder duplizieren Sie einen Trigger in der App	Die Datei wurde in Ihr Repository eingecheckt
Einen Trigger in der App löschen	Die Datei wird aus Ihrem Repository entfernt
Eine Änderung in den verbundenen Zweig übertragen	Der Code des Triggers wird in der App aktualisiert

Jeder Trigger ist eine Datei, die nach ihrem Handle benannt ist und genau das Modul enthält, das Sie im Editor sehen - ohne jegliche zusätzliche Umhüllung. Sie können die Datei also in Ihrem eigenen Editor öffnen, ausführen und wie jede andere JavaScript-Datei auf Fehler prüfen. Anschließend können Sie den oben genannten Endpunkt /test nutzen, um sie vor dem Commit mit einem tatsächlich erfassten Ereignis abzugleichen.

Zurück zu einer früheren Version

Sie müssen sich nicht mit Git auskennen, um eine Änderung rückgängig zu machen. Sobald eine Verbindung zu einem Repository hergestellt ist, zeigt der Trigger-Editor ein Dropdown-Menü „Version“ an, in dem alle früheren Versionen dieser Datei mit Datum und Autor aufgelistet sind. Wählen Sie eine davon aus, und sie wird als ungespeicherte Änderung in den Editor geladen, sodass Sie sie zunächst lesen können - erst durch das Speichern wird sie als neuer Commit wiederhergestellt.

Ändern oder Trennen

Mit „Repository wechseln“ gelangen Sie zurück zur Auswahlliste, ohne die Installation zu verändern. Mit „Trennen“ wird die Installation auf GitHub aufgehoben und hier entfernt - der Name sagt also genau das aus, was damit gemeint ist. Mit „Berechtigungen verwalten“ öffnen Sie die Installationseinstellungen auf GitHub, wo Sie Repositorys hinzufügen oder entfernen können.

Testen von benutzerdefiniertem Trigger-Code

Wenn Sie Ihren benutzerdefinierten Trigger-Code in einem Repository speichern und ihn in Ihrem eigenen Editor bearbeiten, können Sie ihn auf das erfasste Beispielereignis anwenden, ohne ihn zuvor in der App zu speichern.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"

Sie erhalten genau das zurück, was die Schaltfläche „Test“ der App anzeigt: ob der Vorgang ausgelöst würde, das Ausgabeobjekt, Ihre ctx.log-Zeilen sowie die Laufzeit.

Es wird nichts ausgelöst und nichts gespeichert - es wird kein Workflow ausgeführt, kein Ereignis aufgezeichnet, kein Kontingent verbraucht und der gespeicherte Code bleibt unberührt. Die Ausführung bei jedem Speichern durch einen Datei-Watcher ist unbedenklich. Den vollständigen Workflow finden Sie unter Benutzerdefinierte Trigger.

MCP-Server

Auf der Registerkarte „MCP“ der Entwicklerseite werden die Server-URL sowie ein kopierfertiger Verbindungsbefehl für Claude, Cursor, VS Code, Gemini CLI und andere angezeigt. Die Tools spiegeln die REST-Endpunkte wider, und der Tool-Umfang richtet sich nach der Berechtigungsstufe Ihres Schlüssels - bei einem schreibgeschützten Schlüssel sind die Schreib- und Ausführungs-Tools überhaupt nicht sichtbar.

Werkzeug	Stufe	Funktionsweise
list_triggers	lesen	Jeder Trigger und sein Status
list_custom_triggers	lesen	Ihre eigenen benutzerdefinierten Trigger mit dem dazugehörigen Code
get_custom_trigger_sample	lesen	Das erfasste Ereignis, anhand dessen ein benutzerdefinierter Trigger geprüft wird
list_history	lesen	Jüngste Trigger
get_event	lesen	Ein Ereignis einschließlich seines Payloads
get_stats	lesen	Aggregierte Statistiken
get_permissions	lesen	Erteilte Berechtigungen und was sie ermöglichen
get_trigger	schreiben	Ein Trigger im Detail
set_trigger	schreiben	Einen Trigger ein- oder ausschalten
set_triggers_bulk	schreiben	Mehrere gleichzeitig ein- oder ausschalten
simulate_trigger	ausführen	Einen Trigger auf Abruf auslösen
test_custom_trigger	ausführen	Benutzerdefinierten Trigger-Code ausführen, ohne zu speichern oder auszulösen

Das macht einen Assistenten wirklich nützlich: Er kann auflisten, was vorhanden ist, erläutern, was ein Trigger benötigt, ihn aktivieren, ein Testereignis auslösen, das Ergebnis vorlesen - und bei benutzerdefinierten Triggern den Code umschreiben und testen -, ohne dass Sie das Gespräch verlassen müssen.

Wie Ihre Daten geschützt werden

Ereignis-Payloads werden mit maskierten personenbezogenen Daten zurückgegeben: E-Mail-Adressen, Telefonnummern, Kartennummern und Felder mit Personennamen werden zu *** umgewandelt. Ressourcen-IDs (Shopify) und geschäftsbezogene Felder bleiben unverändert, damit der Payload weiterhin nutzbar bleibt.

Die Maskierung wirkt sich auf Feldnamen und Wertmuster aus; sie ist daher sorgfältig, stellt jedoch keine Garantie dar - personenbezogene Daten in einem Freitextfeld können dennoch durchschlagen. Auch Fehlermeldungen werden vor dem Verlassen des Servers um interne Diagnoseangaben bereinigt.

Die GitHub-Verbindung speichert keine Anmeldedaten, die Sie preisgeben könnten: Es wird lediglich die Installations-ID gespeichert, und für den Zugriff auf das Repository wird ein bei Bedarf generiertes Token verwendet, das innerhalb einer Stunde abläuft.

Nächste Schritte

• Benutzerdefinierte Trigger - Erstellen Sie mit wenigen Zeilen JavaScript einen eigenen Trigger.
• Pläne und Nutzung - Was als Ereignis gilt und wie die Beihilfe funktioniert.
• Einführung in Workflow Trigger Extensions - wie Trigger funktionieren und wie man sie aktiviert.

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 aufgebraucht werden, greift eine Häufung von Ausführungen auch auf das gemeinsame Kontingent zurück. Für diese App bedeutet dies die Simulation eines Triggers und die Ausführung von benutzerdefiniertem Trigger-Code - beides löst Ihre Workflows tatsächlich aus.
• Dies gilt für alle Pläne gleichermaßen. Bei Ihrem Plan lösen die Zählerstände Trigger aus, nicht API-Aufrufe; daher führt ein Upgrade nicht zu einem Anstieg dieser Zahlen.
• Es wird der HTTP-Fehler 429 zurückgegeben. Warten Sie eine Weile und versuchen Sie es erneut, idealerweise mit exponentiellem Backoff.
• Sollte unser Cache vorübergehend nicht verfügbar sein, fällt der Begrenzer in den offenen Modus zurück, anstatt Ihre Integration zu blockieren.

Webhooks für eingehende Shopify-Nachrichten unterliegen keiner Ratenbegrenzung

Wir drosseln die Webhooks, die uns Shopify sendet, nicht - sie werden sofort nach Eingang angenommen und in die Warteschlange gestellt. Die Obergrenze ist das 30-Tage-Ereigniskontingent Ihres Plans.

Wenn Sie benutzerdefinierte Trigger schreiben, sollten Sie Folgendes beachten: Ihr Code wird bei jedem Ereignis des Themas ausgeführt, auf das er abhört, und jede Ausführung zählt als ein Ereignis - einschließlich derjenigen, die Sie durch die Rückgabe von null herausfiltern. Der Aufwand entspricht dem eines integrierten Triggers für dasselbe Ereignis.

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 größeren Array 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 gehen müssen, filtern Sie 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-Ratenbeschränkungen