API voor ontwikkelaars, MCP, GitHub en triggersimulatie

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

Een trigger simuleren

Het testen van een Flow-workflow houdt doorgaans in dat u de daadwerkelijke handelingen in uw winkel uitvoert - een product bewerken, een bestelling plaatsen, wachten op een peiling. Simulatie maakt een einde aan dat 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 verwerkingsstroom als een echte webhook van Shopify, zodat uw workflow precies hetzelfde ontvangt als in de productieomgeving.

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 proefdraai 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. U kunt ook {"fromHistoryId":"456"} doorgeven om een eerdere gebeurtenis opnieuw te activeren in plaats van een nieuwe te genereren.

Triggers die via polling worden aangestuurd 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 bovendien 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 uw 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 - bevestigt dat de API actief is
GET	/api/v1/me	lezen	Controleer de authenticatie en bekijk het niveau van uw sleutel
GET	/api/v1/triggers	lezen	Elke trigger, met de bijbehorende status voor uw winkel
GET	/api/v1/triggers/:handle	lezen	Eén trigger in detail
PUT	/api/v1/triggers/:handle	schrijven	Schakel één trigger in of uit
PUT	/api/v1/triggers	schrijven	Meerdere in- of uitschakelen in één opdracht
BERICHT	/api/v1/triggers/:handle/simulate	uitvoeren	Een trigger simuleren
GET	/api/v1/triggers/custom	lezen	Uw eigen aangepaste triggers, inclusief de bijbehorende code
GET	/api/v1/triggers/custom/:handle/test	lezen	De gebeurtenis van het vastgelegde monster voor een aangepaste trigger
BERICHT	/api/v1/triggers/custom/:handle/test	uitvoeren	Aangepaste trigger 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 payload
GET	/api/v1/stats	lezen	Totalen, slagingspercentage, uitsplitsing naar status
GET	/api/v1/permissions	lezen	Welke gegevenstoestemmingen u hebt verleend en welke mogelijkheden deze respectievelijk bieden

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 u deze in de app 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 leidt niet tot een dubbele toepassing van enige bewerking, wat van belang is wanneer een assistent de API aanstuurt.

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 machtiging verleend. Indien de trigger een machtiging nodig heeft die u nog niet hebt verleend, slaagt de aanroep toch en wordt u precies meegedeeld wat er ontbreekt en waar u deze 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 het scherm direct naar de gewenste kaart is 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 opties tegelijk in te schakelen, accepteert PUT /api/v1/triggers zowel een expliciete lijst als een volledige categorie:

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

GitHub koppelen

Op de pagina ‘Ontwikkelaar’ kunt u via het tabblad ‘Verbindingen’ een GitHub-repository koppelen voor uw Aangepaste triggers-code. Wijzigingen worden beschikbaar voor beoordeling in een pull-verzoek; u kunt zien wie wat heeft gewijzigd en u kunt een transformatie ongedaan maken die niet meer werkt.

Als u ‘Verbinden’ selecteert, wordt onze GitHub-app geïnstalleerd op het account van uw keuze. U bepaalt zelf welke repositories de app mag inzien, en u kunt die toegang op elk moment via GitHub intrekken. Wanneer u een repository selecteert, worden alle aangepaste triggers die u al hebt onmiddellijk daarin opgeslagen, zodat de app vanaf het begin al is afgestemd op uw omgeving in plaats van dat deze geleidelijk wordt aangevuld.

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

Elke trigger bestaat uit één bestand dat is vernoemd naar de bijbehorende handle, en dat precies de module bevat die u in de editor ziet - zonder enige extra omhulling. U kunt het dus in uw 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 daadwerkelijk geregistreerde gebeurtenis voordat u de wijzigingen vastlegt.

Terugkeren naar een eerdere versie

U 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, voorzien van de datum en de auteur. Kies er een uit en deze wordt in de editor geladen als een niet-opgeslagen wijziging, zodat u deze eerst kunt bekijken - pas wanneer u opslaat, wordt de wijziging teruggezet als een nieuwe commit.

Wijzigen of loskoppelen

Met ‘Repository wijzigen’ keert u terug naar de keuzelijst zonder de installatie te wijzigen. 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’ opent u de installatie-instellingen op GitHub, waar u repositories kunt toevoegen of verwijderen.

Het testen van aangepaste triggercode

Als u uw aangepaste trigger-code in een repository bewaart en deze in uw eigen editor bewerkt, kunt u deze uitvoeren op de vastgelegde voorbeeldgebeurtenis zonder deze eerst in de app op te slaan.

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

U krijgt terug wat de knop ‘Test’ van de app weergeeft: of de actie zou worden geactiveerd, het uitvoerobject, uw regels ctx.log 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. U kunt dit zonder risico uitvoeren telkens wanneer er vanuit een bestandsbewaker wordt opgeslagen. Zie Aangepaste triggers voor de volledige workflow.

MCP-server

Op het tabblad ‘MCP’ op de pagina ‘Ontwikkelaar’ 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 afgestemd op het niveau van uw sleutel - bij een sleutel met alleen-lezen-toegang zijn de schrijf- en uitvoertools helemaal niet zichtbaar.

Hulpmiddel	Niveau	Wat het doet
list_triggers	lezen	Elke trigger en de status daarvan
list_custom_triggers	lezen	Uw eigen aangepaste triggers, inclusief de bijbehorende code
get_custom_trigger_sample	lezen	De geregistreerde gebeurtenis waaraan een aangepaste trigger toetst
list_history	lezen	Recente gebeurtenissen die als trigger hebben gediend
get_event	lezen	Eén gebeurtenis, inclusief de payload
get_stats	lezen	Geaggregeerde statistieken
get_permissions	lezen	Toegekende rechten en wat deze mogelijk maken
get_trigger	schrijven	Eén trigger in detail
set_trigger	schrijven	Schakel één trigger in of uit
set_triggers_bulk	schrijven	Meerdere tegelijk in- of uitschakelen
simulate_trigger	uitvoeren	Een trigger op verzoek activeren
test_custom_trigger	uitvoeren	Aangepaste trigger uitvoeren zonder op te slaan of te activeren

Dit is wat een assistent werkelijk nuttig maakt: hij kan in kaart brengen wat er beschikbaar 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 u 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 omgezet in ***. Shopify-bron-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 blijven. Ook worden foutmeldingen ontdaan van interne diagnostische details voordat ze de server verlaten.

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

Volgende stappen

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

Verwerkingslimieten

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, strikter budget van 60 per uur. Beide worden verbruikt, dus een piek in het aantal uitvoeringen tast ook de gedeelde toewijzing aan. Voor deze app betekent dit het simuleren van een trigger en het uitvoeren van een aangepaste trigger, twee activiteiten die uw workflows daadwerkelijk in gang zetten.
• Dit geldt voor elk abonnement. Uw abonnementsmeters triggeren gebeurtenissen, geen API-aanroepen, dus een upgrade leidt niet tot een stijging van deze cijfers.
• Er wordt een HTTP 429-foutcode geretourneerd. Wacht even en probeer het opnieuw, bij voorkeur met exponentiële wachttijd.
• Mocht onze cache tijdelijk niet beschikbaar zijn, dan schakelt de begrenzer uit in plaats van uw integratie te blokkeren.

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

Wij beperken de webhooks die Shopify ons toestuurt niet - deze 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 belangrijk punt om te weten als u aangepaste triggers schrijft: uw code wordt bij elke gebeurtenis van het onderwerp waarop deze luistert uitgevoerd, en elke uitvoering telt als één gebeurtenis, ook de gebeurtenissen die u 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 uw workflows) kunnen doen aan de kant van Shopify, en het kan voorkomen dat u hiertegen aanloopt bij een grote winkel, zelfs als u ruim binnen onze limieten blijft.

• Het aantal elementen in invoerarrays is beperkt tot 250 voor alle API’s van Shopify. Een verzoek met een array die deze limiet overschrijdt, wordt afgewezen.
• De paginering stopt bij 25.000 objecten. De tellingen zijn nauwkeurig tot 25.000; daarboven retourneert Shopify 25001, wat betekent „meer dan 25.000“. Indien u verder wilt gaan, dient u eerst te filteren.
• Het gebruik van de GraphQL Admin API wordt gemeten aan de hand van de berekende querykosten, uitgedrukt in punten per seconde, en het maximum hangt af van het Shopify-abonnement van de winkel:

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

De webshop-API kent geen verwerkingslimiet.

Volledige informatie: Shopify API-limieten