API voor ontwikkelaars en MCP

Alles wat u in de app beheert, kunt u ook vanuit uw eigen code of via een AI-assistent beheren. Workflow Webhooks biedt twee interfaces: een REST-API en een MCP-server. Beide zijn te vinden op de pagina voor ontwikkelaars.

API-sleutels

Beide platforms verifiëren de identiteit aan de hand van een API-sleutel. Maak op de pagina ‘Ontwikkelaar’, onder ‘API-sleutels’, een sleutel aan en kies het toegangsniveau:

Alleen-lezen - webhooks weergeven, de geschiedenis van aanroepen en statistieken bekijken.
Lezen en schrijven - en tevens webhooks aanmaken, bijwerken en verwijderen.
Lezen, schrijven en uitvoeren - u kunt ook een testaanroep starten of een eerdere aanroep opnieuw afspelen.

De volledige sleutel wordt één keer weergegeven, namelijk bij het aanmaken ervan. Kopieer deze dan en bewaar hem op een veilige plaats; u kunt hem daarna niet meer inzien. Sleutels worden in gehasht vorm opgeslagen, nooit in leesbare tekst, en u kunt een sleutel op elk moment intrekken.

Stuur de sleutel bij elk verzoek mee als een Bearer-token:

text

Authorization: Bearer fwk_your_key_here

Waarom ‘uitvoeren’ een apart niveau vormt

Het activeren van een Webhook zet daadwerkelijk uw Shopify Flow-workflows in gang, en die workflows kunnen wijzigingen in uw winkel aanbrengen - zoals het toekennen van tags aan bestellingen, het versturen van e-mails of het bijwerken van de voorraad. Door dit op een apart niveau te houden, voorkomt u dat een sleutel die u aan een script of een AI-assistent toekent voor dagelijkse taken, per ongeluk uw automatiseringen in gang zet. Deel standaard leessleutels uit en maak alleen een uitvoersleutel aan wanneer u deze daadwerkelijk nodig hebt.

Basis-URL

De API en de MCP-server worden aangeboden via een specifieke hostnaam:

text

https://shopify.workflow-webhooks.app

De REST API is dus te vinden op https://shopify.workflow-webhooks.app/api/v1 en de MCP-server op https://shopify.workflow-webhooks.app/api/mcp. Op de ontwikkelaarspagina worden beide weergegeven, samen met een knop ‘Kopiëren’.

Deze hostnaam verwijst uitsluitend naar /api - de ingebouwde beheerdersinterface blijft op zijn eigen, bij Shopify geregistreerde URL staan. Door deze twee gescheiden te houden, blijft het adres dat u in een script, een CI-taak of een AI-client invoert stabiel en staat het los van de integratie van de app.

REST-API

De basis-URL wordt weergegeven op de pagina ‘Ontwikkelaar’. De belangrijkste eindpunten:

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/webhooks`	lezen	Webhooks weergeven
BERICHT	`/api/v1/webhooks`	schrijven	Een webhook aanmaken
GET	`/api/v1/webhooks/:id`	lezen	Maak één webhook aan
PUT / PATCH	`/api/v1/webhooks/:id`	schrijven	Een webhook bijwerken
VERWIJDEREN	`/api/v1/webhooks/:id`	schrijven	Een webhook verwijderen
BERICHT	`/api/v1/webhooks/:id/test`	uitvoeren	Voer een testaanroep uit
GET	`/api/v1/history`	lezen	Lijstaanroepen
GET	`/api/v1/history/:id`	lezen	Haal één aanroep op, inclusief de bijbehorende payload
BERICHT	`/api/v1/history/:id/replay`	uitvoeren	Een eerdere aanroeping opnieuw afspelen
GET	`/api/v1/stats`	lezen	Totalen, slagingspercentage, dagelijkse reeks
GET	`/api/v1/templates`	lezen	Ingebouwde webhook-sjablonen

Een snelle controle of uw sleutel werkt:

bash

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

json

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

MCP-server

Met de MCP-server kan een AI-assistent (Claude, Cursor, VS Code, Gemini CLI en andere) tijdens een gesprek gebruikmaken van uw webhooks. Op de pagina ‘Developer’ toont het tabblad ‘MCP’ de server-URL en een kant-en-klare verbindingsopdracht per client, waarin uw sleutel al is ingevuld.

De tools zijn een afspiegeling van de REST-eindpunten, en de set tools is afgestemd op het niveau van uw sleutel: bij een sleutel met alleen-lezen-toegang zijn de tools voor het aanmaken, verwijderen of activeren van webhooks niet eens zichtbaar. Alle authenticatie en gegevensverwerking vinden plaats aan de serverzijde.

Hoe uw gegevens worden beschermd

Er zijn twee zaken die u moet weten voordat u een automatisering of een AI-assistent op deze API richt.

Het authenticatietoken van uw webhook is nooit leesbaar. Het token of het ondertekeningsgeheim dat u voor een webhook instelt, kan op geen enkel niveau via de API of het MCP worden uitgelezen. Uit de reacties blijkt alleen of er een token is ingesteld (hasToken), maar nooit wat de waarde ervan is. U kunt een nieuw token instellen; het oude token kunt u nooit opvragen.

Persoonsgegevens in payloads worden gemaskeerd. Webhook-payloads zijn afkomstig van externe systemen en bevatten vaak klantgegevens. Voordat een payload van een aanroep de server verlaat, worden waarden die op persoonsgegevens lijken vervangen door ***: e-mailadressen, telefoonnummers, kaartnummers en velden die naar een persoon zijn vernoemd (customerName, shippingAddress en dergelijke). Verzoekheaders worden op dezelfde manier opgeschoond als op het geschiedenisscherm van de app.

Deze maskering is zorgvuldig uitgevoerd, maar biedt geen garantie. De methode is gebaseerd op veldnamen en waardepatronen, waardoor persoonsgegevens die in een vrijtekstveld staan - zoals een notitie, een opmerking of de tekst van een bericht - nog steeds zichtbaar kunnen zijn. Ga er bij API-antwoorden vanuit dat deze mogelijk klantgegevens bevatten en sla ze dienovereenkomstig op.

Testen en herhalen hebben geen invloed op uw quotum. Aanroepen die u via de API uitvoert, worden geregistreerd als tests en tellen dus niet mee voor de maandelijkse limiet van uw abonnement. Herhalingen tellen evenmin mee, aangezien de oorspronkelijke aanroep al is meegeteld.

Volgende stappen

Inleiding tot Workflow Webhooks - hoe webhooks en payload-toewijzing werken.

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, krapper 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 testen van een webhook en het opnieuw afspelen van een geschiedenisitem, waarbij in beide gevallen daadwerkelijk uw Shopify Flow-workflows worden uitgevoerd.
Dit geldt voor elk abonnement. Uw abonnement houdt het aantal aanroepen bij, niet het aantal API-aanroepen, dus een upgrade leidt niet tot een stijging van deze aantallen.
Er wordt een HTTP 429-foutcode geretourneerd. Wacht even en probeer het opnieuw, bij voorkeur met exponentiële backoff.
Mocht onze cache tijdelijk niet beschikbaar zijn, dan werkt de beperker op een ‘fails open’-manier in plaats van uw integratie te blokkeren.

Er geldt geen limiet voor het aantal inkomende webhooks

Het is de moeite waard om dit duidelijk te maken, aangezien dit de vraag is die ons het vaakst wordt gesteld: wij beperken de inkomende webhook-berichten niet. Wij verzenden ze net zo snel als ze binnenkomen, ongeacht de pieken die uw bronsysteem genereert - er geldt aan onze kant geen limiet per seconde of per minuut.

De enige beperking is de toegestane 30 dagen voor het gebruik van uw abonnement. Zodra deze is opgebruikt, worden verdere aanroepen niet meer verwerkt totdat de periode opnieuw begint of u een upgrade uitvoert. Daarnaast gelden de limieten van Shopify: Shopify Flow heeft zijn eigen uitvoeringslimieten en de omvang van een trigger-payload is beperkt tot 50 KB.

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 webwinkel, 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 de waarde 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 limiet op het aantal verzoeken.

Volledige informatie: Shopify API-limieten