Ontwikkelaars-API, MCP, GitHub en triggersimulatie

Je kunt je triggers bekijken, ze in- of uitschakelen, de gebeurtenisgeschiedenis bekijken en een trigger simuleren vanuit je eigen code of vanuit een AI-assistent. Workflow Trigger Extensions biedt een REST-API en een MCP-server, en kan verbinding maken met een GitHub-repository, zodat je aangepaste triggercode onder versiebeheer valt. Alle drie worden ze beheerd op de pagina ‘Developer’.

Een trigger simuleren

Het testen van een Flow-workflow houdt normaal gesproken in dat je de daadwerkelijke handeling in je winkel uitvoert: een product bewerken, een bestelling plaatsen, wachten op een poll. Met simulatie hoef je niet te wachten: kies een trigger, koppel deze aan een bron, en de trigger wordt geactiveerd alsof de daadwerkelijke gebeurtenis zojuist heeft plaatsgevonden.

Twee manieren om er één uit te voeren:

In de app. Open een willekeurige gebeurtenis in de gebeurtenisgeschiedenis en kies opnieuw voor ‘Simuleren’. Hierdoor wordt precies die gebeurtenis opnieuw geactiveerd.
Via de API of MCP, met een resource-ID of een gebeurtenis uit het verleden.

De simulatie is bewust zo nauwkeurig mogelijk. Er wordt geen verkorte payload gegenereerd - de simulatie doorloopt dezelfde pijplijn als een echte webhook van Shopify, dus wat je workflow ontvangt, is precies wat deze in de productieomgeving zou ontvangen.

Dry run firstbash

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}'

Bij een testrun wordt de trigger gevalideerd, het onderwerp afgehandeld en de payload weergegeven - zonder dat er daadwerkelijk iets wordt geactiveerd. Verwijder dryRun om de trigger daadwerkelijk te activeren. Je kunt ook {"fromHistoryId":"456"} doorgeven om een eerdere gebeurtenis opnieuw te activeren in plaats van een nieuwe te genereren.

Triggers die worden aangestuurd door polling in plaats van via een webhook, kunnen niet worden gesimuleerd; deze worden in de triggerlijst weergegeven als simulatable: false.

API-sleutels

Maak een sleutel aan op de pagina ‘Ontwikkelaar’ en kies het toegangsniveau:

Alleen-lezen: een overzicht van triggers en hun status, de gebeurtenisgeschiedenis, statistieken en machtigingen bekijken.
Lezen en schrijven - en ook de triggers in- en uitschakelen.
Lezen, schrijven en uitvoeren - simuleer ook triggers en test aangepaste triggercode.

De volledige sleutel wordt één keer weergegeven, bij het aanmaken ervan. Sleutels worden in gehasht vorm opgeslagen en kunnen op elk moment worden ingetrokken. Verstuur deze als een Bearer-token:

Authorization: Bearer ftk_your_key_here

Simulation bevindt zich om bovengenoemde reden op een apart niveau: het voert je automatiseringen daadwerkelijk uit, zodat een sleutel die voor dagelijkse leesbewerkingen wordt gebruikt, deze niet kan activeren.

REST-API

Methode	Pad	Niveau	Doel
GET	`/api/v1`	geen	API-index - geeft aan dat de API actief is
GET	`/api/v1/me`	lezen	Controleer de authenticatie en bekijk het niveau van je sleutel
GET	`/api/v1/triggers`	lezen	Elke trigger, met de bijbehorende status voor jouw winkel
GET	`/api/v1/triggers/:handle`	lezen	Eén trigger in detail
PUT	`/api/v1/triggers/:handle`	schrijven	Een trigger in- of uitschakelen
PUT	`/api/v1/triggers`	schrijven	Meerdere in- of uitschakelen in één opdracht
POST	`/api/v1/triggers/:handle/simulate`	uitvoeren	Een trigger simuleren
GET	`/api/v1/triggers/custom`	lezen	Je eigen aangepaste triggers, inclusief de bijbehorende code
GET	`/api/v1/triggers/custom/:handle/test`	lezen	De gebeurtenis voor het vastleggen van een monster bij een aangepaste trigger
POST	`/api/v1/triggers/custom/:handle/test`	uitvoeren	Aangepaste triggercode uitvoeren zonder op te slaan of te activeren
GET	`/api/v1/history`	lezen	Lijst met triggergebeurtenissen
GET	`/api/v1/history/:id`	lezen	Haal één gebeurtenis op, inclusief de bijbehorende payload
GET	`/api/v1/stats`	lezen	Totalen, slagingspercentage, uitsplitsing per status
GET	`/api/v1/permissions`	lezen	Welke gegevenstoestemmingen je hebt verleend en wat je daarmee allemaal kunt doen

GET /api/v1/triggers Dit is handig bij het instellen: voor elke trigger wordt aangegeven welke toestemming er nodig is, of die toestemming is verleend, of de trigger is ingeschakeld en waar in de app je deze kunt beheren.

Triggers in- en uitschakelen

PUT wordt gebruikt in plaats van PATCH, omdat de aanroep idempotent is - het opnieuw uitvoeren ervan na een time-out kan nergens tot een dubbele toepassing leiden, wat van belang is wanneer een assistent de API aanstuurt.

Enable one triggerbash

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}'

Met 'Enabling' wordt nooit een toestemming verleend. Als de trigger een toestemming nodig heeft die je nog niet hebt verleend, wordt de aanroep toch uitgevoerd en krijg je precies te zien wat er ontbreekt en waar je de toestemming moet verlenen:

{
  "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."
}

Via die link wordt de pagina ‘Toestemmingen’ geopend, waarbij je direct naar de gewenste kaart wordt gescrolld.

Voeg "sync": true toe om ook een gegevenssynchronisatie te starten, zodat de trigger werkt op records die al bestaan en niet alleen op records die vanaf nu worden aangemaakt.

Om meerdere tegelijk te wijzigen, accepteert PUT /api/v1/triggers een expliciete lijst of een hele categorie:

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

GitHub koppelen

Op de pagina ‘Developer’ kun je via het tabblad ‘Connections’ een GitHub-repository koppelen voor je Aangepaste triggers-code. Wijzigingen worden zichtbaar in een pull-verzoek, je kunt zien wie wat heeft gewijzigd en je kunt een transformatie ongedaan maken die niet meer werkt.

Als je ‘Verbinden’ selecteert, wordt onze GitHub-app geïnstalleerd op het account dat je kiest. Je bepaalt zelf welke repositories de app mag zien, en je kunt die toegang op elk moment via GitHub intrekken. Als je een repository selecteert, worden alle aangepaste triggers die je al hebt onmiddellijk daarin opgeslagen, zodat de app meteen goed is afgestemd op de app in plaats van dat dit geleidelijk gebeurt.

Wat je doet	Wat gebeurt er?
Een trigger aanmaken, bewerken of dupliceren in de app	Het bestand is opgeslagen in je repository
Een trigger in de app verwijderen	Het bestand is uit je repository verwijderd
Een wijziging doorvoeren in de gekoppelde branch	De code van de trigger wordt in de app bijgewerkt

Elke trigger bestaat uit één bestand dat naar de handle is vernoemd en dat precies de module bevat die je in de editor ziet - zonder enige extra omhulling. Je kunt het dus in je eigen editor openen, uitvoeren en op fouten controleren zoals elk ander JavaScript-bestand, en vervolgens het bovenstaande eindpunt /test gebruiken om het uit te voeren op een echte geregistreerde gebeurtenis voordat je de wijzigingen vastlegt.

Teruggaan naar een eerdere versie

Je hoeft geen kennis van Git te hebben om een wijziging ongedaan te maken. Zodra er verbinding is gemaakt met een repository, toont de trigger-editor een vervolgkeuzemenu ‘Versie’ met daarin alle eerdere versies van dat bestand, inclusief de datum en de auteur. Kies er een uit en deze wordt in de editor geladen als een niet-opgeslagen wijziging, zodat je deze eerst kunt bekijken. Pas als je opslaat, wordt de wijziging teruggezet als een nieuwe commit.

Wijzigen of loskoppelen

Met ‘Repository wijzigen’ ga je terug naar de keuzelijst zonder de installatie aan te raken. Met ‘Verbinding verbreken’ wordt de installatie zowel op GitHub ongedaan gemaakt als hier verwijderd; de naam zegt dus precies wat het doet. Met ‘Toegangsrechten beheren’ open je de installatie-instellingen op GitHub, waar je repositories kunt toevoegen of verwijderen.

Aangepaste triggercode testen

Als je je aangepaste triggercode in een repository bewaart en deze in je eigen editor bewerkt, kun je deze uitvoeren op de vastgelegde voorbeeldgebeurtenis zonder deze eerst in de app op te slaan.

Test the file you are editingbash

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}')"

Je krijgt terug wat de knop ‘Test’ van de app weergeeft: of de actie zou worden uitgevoerd, het uitvoerobject, je ctx.log-regels en de uitvoertijd.

Er wordt niets geactiveerd en er wordt niets opgeslagen - er wordt geen workflow uitgevoerd, er wordt geen gebeurtenis geregistreerd, er wordt geen quotum verbruikt en de opgeslagen code blijft ongewijzigd. Het is veilig om dit bij elke opslag door een bestandsbewaker uit te voeren. Zie Aangepaste triggers voor de volledige workflow.

MCP-server

Op het tabblad ‘MCP’ op de ontwikkelaarspagina worden de server-URL en een kant-en-klare verbindingsopdracht weergegeven voor Claude, Cursor, VS Code, Gemini CLI en andere tools. De tools volgen de REST-eindpunten, en de beschikbare tools zijn afhankelijk van het niveau van je sleutel: bij een sleutel met alleen-lezen-toegang zijn de tools voor schrijven of uitvoeren helemaal niet zichtbaar.

Hulpmiddel	Niveau	Wat het doet
`list_triggers`	lezen	Elke trigger en de status ervan
`list_custom_triggers`	lezen	Je eigen aangepaste triggers, inclusief de bijbehorende code
`get_custom_trigger_sample`	lezen	De vastgelegde gebeurtenis waartegen een aangepaste trigger toetst
`list_history`	lees	Recente gebeurtenissen die aanleiding gaven tot…
`get_event`	lezen	Eén object, inclusief de lading
`get_stats`	lezen	Geaggregeerde statistieken
`get_permissions`	lezen	Toegekende rechten en wat ze mogelijk maken
`get_trigger`	schrijven	Eén trigger in detail
`set_trigger`	schrijven	Een trigger in- of uitschakelen
`set_triggers_bulk`	schrijven	Meerdere tegelijk in- of uitschakelen
`simulate_trigger`	uitvoeren	Een trigger op verzoek activeren
`test_custom_trigger`	uitvoeren	Aangepaste triggercode uitvoeren zonder op te slaan of te activeren

Dit is wat een assistent echt nuttig maakt: hij kan in kaart brengen wat er allemaal is, uitleggen wat een trigger nodig heeft, deze inschakelen, een testgebeurtenis activeren, het resultaat teruglezen - en bij aangepaste triggers de code herschrijven en testen - zonder dat je het gesprek hoeft te verlaten.

Hoe uw gegevens worden beschermd

De payloads van gebeurtenissen worden teruggestuurd met gemaskeerde persoonsgegevens: e-mailadressen, telefoonnummers, kaartnummers en velden met persoonsnamen worden vervangen door ***. Shopify-resource-ID’s en zakelijke velden blijven ongewijzigd, zodat de payload bruikbaar blijft.

Het maskeren is van toepassing op veldnamen en waardepatronen; het biedt dus een zekere mate van bescherming, maar geen garantie - persoonsgegevens in een vrijtekstveld kunnen nog steeds zichtbaar zijn. Ook worden foutmeldingen ontdaan van interne diagnostische details voordat ze de server verlaten.

De GitHub-verbinding slaat geen inloggegevens op die je zou kunnen lekken: alleen het installatie-ID wordt bewaard, en voor toegang tot de repository wordt gebruikgemaakt van een token dat op verzoek wordt aangemaakt en binnen een uur verloopt.

Volgende stappen

Aangepaste triggers - maak zelf een trigger met een paar regels JavaScript.
Plannen en gebruik - wat als een gebeurtenis wordt beschouwd en hoe de vergoeding werkt.
Inleiding tot Workflow Trigger Extensions - hoe triggers werken en hoe je ze kunt inschakelen.

Beperkingen op het aantal verzoeken

De REST API en de MCP-server delen één budget per API-sleutel.

300 verzoeken per 60 seconden per sleutel, als een vast tijdsvenster.
Voor aanroepen op uitvoeringsniveau geldt een tweede, krapper budget van 60 per uur. Beide worden verbruikt, dus een reeks uitvoeringen put ook het gedeelde budget uit. Voor deze app betekent dit het simuleren van een trigger en het uitvoeren van aangepaste triggercode, die beide je workflows daadwerkelijk in gang zetten.
Dat geldt voor elk abonnement. De tellers van je abonnement activeren gebeurtenissen, geen API-aanroepen, dus een upgrade heeft geen invloed op deze cijfers.
Er wordt een HTTP 429-foutmelding teruggestuurd. Wacht even en probeer het opnieuw, bij voorkeur met exponentiële backoff.
Mocht onze cache tijdelijk niet beschikbaar zijn, dan schakelt de beperker uit in plaats van je integratie te blokkeren.

Webhooks voor inkomende Shopify-verzoeken zijn niet onderworpen aan een limiet op het aantal verzoeken

We beperken de webhooks die Shopify ons stuurt niet - ze worden direct bij ontvangst geaccepteerd en in de wachtrij geplaatst. De limiet is het aantal gebeurtenissen dat binnen 30 dagen is toegestaan volgens uw abonnement.

Een ding dat je moet weten als je aangepaste triggers schrijft: je code wordt bij elke gebeurtenis van het topic waarnaar deze luistert uitgevoerd, en elke uitvoering telt als één gebeurtenis, ook de gebeurtenissen die je eruit filtert door null te retourneren. Dit kost evenveel als de ingebouwde trigger voor dezelfde gebeurtenis zou kosten.

Shopify

Dit zijn de limieten die Shopify hanteert voor de API’s van Shopify, niet die van ons. Ze zijn van toepassing op wat deze app (en je workflows) kunnen doen aan de kant van Shopify, en het kan zijn dat je bij een grote winkel tegen deze limieten aanloopt, zelfs als je ruim binnen onze limieten blijft.

Het aantal items in invoerarrays is beperkt tot 250 voor alle API’s van Shopify. Een verzoek met een grotere array wordt afgewezen.
De paginering stopt bij 25.000 objecten. De tellingen zijn nauwkeurig tot 25.000; daarboven geeft Shopify de waarde 25001 terug, wat betekent: "meer dan 25.000". Als je verder wilt gaan, filter dan eerst.
Het gebruik van de GraphQL Admin API wordt gemeten aan de hand van de berekende querykosten, in punten per seconde, en het maximum hangt af van het Shopify-abonnement van de winkel:

Shopify plan	Punten per seconde
Standaard	100
Gevorderd	200
Plus	1000
Enterprise (commerciële componenten)	2000

De Storefront API kent geen limiet op het aantal verzoeken.

Volledige informatie: Shopify API-limieten