Entwickler-API, MCP, GitHub und Triggersimulation
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 Entwickler-Seite verwaltet.
Simulation eines Auslösers
Das Testen eines Flow-Workflows bedeutet normalerweise, den tatsächlichen Ablauf in Ihrem Shop nachzustellen - ein Produkt bearbeiten, eine Bestellung aufgeben, auf eine Umfrage warten. Durch die Simulation entfällt diese Wartezeit: Wählen Sie einen Auslöser aus, ordnen Sie ihn einer Ressource zu, und er wird ausgelöst, als wäre das tatsächliche Ereignis gerade eingetreten.
Zwei Möglichkeiten, eine auszuführen:
- In der App: Öffnen Sie 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 Nutzlast 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 Nutzlast 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 vergangenes Ereignis erneut auszulösen, anstatt ein neues zu erstellen.
Trigger, die über Polling 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 - Trigger und deren Status auflisten, Ereignisverlauf, Statistiken und Berechtigungen einsehen.
- Lesen und Schreiben - außerdem das Ein- und Ausschalten von Auslösern.
- Lesen, schreiben und ausführen - außerdem Trigger simulieren und benutzerdefinierten Trigger-Code testen.
Der vollständige Schlüssel wird einmalig bei der Erstellung angezeigt. Schlüssel werden in gehashtem Form gespeichert und können jederzeit widerrufen werden. Senden Sie ihn als Bearer-Token:
Authorization: Bearer ftk_your_key_hereDie 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 Auslöser im Detail |
| PUT | /api/v1/triggers/:handle |
schreiben | Einen Auslöser ein- oder ausschalten |
| PUT | /api/v1/triggers |
schreiben | Mehrere Geräte in einem Aufruf 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 ihrem Code |
| GET | /api/v1/triggers/custom/:handle/test |
lesen | Das Ereignis der erfassten 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 | Triggerereignisse auflisten |
| GET | /api/v1/history/:id |
lesen | Ein Ereignis mit seiner Nutzlast 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 freigeschaltet werden |
GET /api/v1/triggers ist für die Einrichtung sehr hilfreich: Für jeden Trigger wird angezeigt, welche Berechtigung erforderlich ist, ob diese Berechtigung erteilt wurde, ob der Trigger aktiviert ist und wo in der App er verwaltet werden kann.
Auslöser ein- und ausschalten
PUT wird anstelle von PATCH verwendet, da der Aufruf idempotent ist - eine Wiederholung nach Ablauf des Timeouts kann keine doppelte Anwendung bewirken, was wichtig 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. Wenn der Trigger eine Berechtigung benötigt, die Sie noch nicht erteilt haben, wird der Aufruf dennoch erfolgreich ausgeführt und es wird Ihnen genau angezeigt, 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 markiert ist.
Fügen Sie "sync": true hinzu, um zusätzlich eine Datensynchronisierung zu starten, sodass der Trigger auch auf bereits vorhandene Datensätze angewendet wird und nicht nur auf solche, die ab sofort angelegt werden.
Um mehrere auf einmal umzuschalten, akzeptiert PUT /api/v1/triggers eine explizite Liste oder eine ganze 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 auf der Registerkarte „Verbindungen“ ein GitHub-Repository für Ihren Benutzerdefinierte Auslöser-Code verknüpfen. Änderungen können dann in einem Pull-Request überprüft werden, Sie können sehen, wer was geändert 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 zugreifen darf, 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 den Daten synchronisiert ist und diese nicht erst im Laufe der Zeit ergänzt werden müssen.
| Was du tust | Was passiert? |
|---|---|
| Einen Trigger in der App erstellen, bearbeiten oder duplizieren | Die Datei wurde in Ihr Repository übertragen. |
| Einen Trigger in der App löschen | Die Datei wird aus Ihrem Repository entfernt. |
| Eine Änderung an 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.
Zu einer früheren Version zurückkehren
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 ändern“ gelangen Sie zurück zur Auswahl, ohne die Installation zu verändern. „Trennen“ hebt die Installation auf GitHub auf und entfernt sie auch hier - der Name sagt also bereits alles. „Berechtigungen verwalten“ öffnet 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 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 Befehl ausgeführt würde, das Ausgabeobjekt, Ihre Zeilen aus ctx.log 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. Der Workflow kann bedenkenlos bei jedem Speichern durch einen Datei-Watcher ausgeführt werden. Den vollständigen Workflow finden Sie unter Benutzerdefinierte Auslöser.
MCP-Server
Auf der Registerkarte „MCP“ der Entwicklerseite werden die Server-URL und 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 | Was es bewirkt |
|---|---|---|
list_triggers |
lesen | Jeder Trigger und sein Status |
list_custom_triggers |
lesen | Ihre eigenen benutzerdefinierten Trigger mit ihrem Code |
get_custom_trigger_sample |
lesen | Das erfasste Ereignis, anhand dessen ein benutzerdefinierter Trigger geprüft wird |
list_history |
lesen | Jüngste auslösende Ereignisse |
get_event |
lesen | Ein Ereignis einschließlich seiner Nutzlast |
get_stats |
lesen | Aggregierte Statistiken |
get_permissions |
lesen | Erteilte Berechtigungen und was sie ermöglichen |
get_trigger |
schreiben | Ein Auslöser im Detail |
set_trigger |
schreiben | Einen Auslöser ein- oder ausschalten |
set_triggers_bulk |
schreiben | Mehrere gleichzeitig ein- oder ausschalten |
simulate_trigger |
ausführen | Einen Trigger nach Bedarf 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, erklären, 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.
So werden Ihre Daten geschützt
Ereignis-Payloads werden mit maskierten personenbezogenen Daten zurückgegeben: E-Mail-Adressen, Telefonnummern, Kartennummern und Felder mit Personennamen werden zu *** umgewandelt. Shopify Ressourcen-IDs und geschäftsbezogene Felder bleiben unverändert, damit der Payload weiterhin nutzbar bleibt.
Die Maskierung wirkt sich auf Feldnamen und Wertmuster aus, ist also sorgfältig, bietet jedoch keine Garantie - 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 Auslöser - Erstellen Sie mit wenigen Zeilen JavaScript einen eigenen Trigger.
- Pläne und Nutzung - Was gilt als Ereignis und wie funktioniert die Beihilfe?
- 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.
- Für Aufrufe auf Ausführungsebene gilt ein zweites, strafferes 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 das die Simulation eines Triggers und die Ausführung von benutzerdefiniertem Trigger-Code - beides löst Ihre Workflows tatsächlich aus.
- Das gilt für alle Tarife gleichermaßen. Bei Ihrem Tarif lösen die Zählerstände Ereignisse aus, nicht API-Aufrufe, sodass ein Upgrade diese Zahlen nicht erhöht.
- Es wird der HTTP-Fehler 429 zurückgegeben. Warte eine Weile und versuche es erneut, idealerweise mit exponentiellem Backoff.
- Sollte unser Cache vorübergehend nicht verfügbar sein, fällt der Begrenzer auf „offen“ zurück, anstatt Ihre Integration zu blockieren.
Webhooks für eingehende Shopify-Anfragen 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 Tarifs.
Wenn Sie benutzerdefinierte Trigger schreiben, sollten Sie Folgendes wissen: Ihr Code wird bei jedem Ereignis des Themas ausgeführt, das er überwacht, und jede Ausführung zählt als ein Ereignis - auch diejenigen, die Sie durch die Rückgabe von null herausfiltern. Die Kosten entsprechen denen 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 legen fest, was diese App (und Ihre Workflows) auf der Seite von Shopify tun 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 in 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
25001zurück, was „mehr als 25.000“ bedeutet. Wenn Sie tiefer in die Daten einsteigen möchten, filtern Sie diese zunächst. - Die GraphQL-Admin-API wird anhand der berechneten Abfragekosten in Punkten pro Sekunde abgerechnet, wobei die Obergrenze vom jeweiligen Shopify-Tarif des Shops abhängt:
| Shopify Plan | Punkte pro Sekunde |
|---|---|
| Standard | 100 |
| Fortgeschritten | 200 |
| Außerdem | 1000 |
| Enterprise (Handelskomponenten) | 2000 |
Die Storefront-API unterliegt keiner Ratenbegrenzung.
Alle Details: Shopify API-Ratenbegrenzungen