Workflow SuiteWorkflow Suite

Incoming webhooks

The trigger Incoming webhook gives a workflow its own secret URL. Another system, such as an ERP, a warehouse, a form tool or a script, sends a POST request to that URL, and the workflow starts with the request as its event.

Set it up

  1. Select the trigger, Change trigger, and pick Incoming webhook.
  2. Save the workflow. Until then the panel says Save the workflow to get its webhook URL.
  3. Copy the Webhook URL from the trigger panel. It is a secret URL on shopify.workflow-suite.app.
  4. The panel also shows an Example request you can copy and run from a terminal.
  5. Turn the workflow on. A workflow that is off answers with an error and starts nothing.

A workflow created from a template, duplicated or created over the API gets its own URL. A duplicate never shares the URL of the original.

What the steps read

Variable Holds
event.payload.body The JSON body of the request
event.payload.query The query parameters of the URL
event.payload.headers A small set of request headers: content type, user agent, request id, x-event-type, x-event-id, x-signature and x-hub-signature-256

Example: the other system sends a SKU and a quantity.

{ "sku": "ABC-1", "quantity": 12 }

A later step reads them as:

{{ event.payload.body.sku }} and {{ event.payload.body.quantity }}

To test without the other system, paste a body like the one above into Event (JSON) in the Test panel, under body.

What the caller gets back

Answer Meaning
202 with started: true A run was started
202 with started: false Nothing started. reason is filtered (the trigger filter rejected it) or suppressed (loop protection or the plan limit stopped it)
404 The URL is not known
405 The request was not a POST
409 The workflow is turned off
413 The body is larger than 256 KB
429 More than 120 requests in a minute. Wait a minute and try again

The answer comes at once. It does not wait for the run and does not carry its result. The other system can look the run up over the Developer API. See Developer API and MCP.

Good to know

  • Use a trigger filter to ignore requests you do not want. Rejected requests start nothing and do not count against your plan. See Trigger filters.
  • End the workflow with a Fail the run step on the path where the data is wrong, for example when no variant has the SKU. The run then shows as Failed with your message, and you get the failure alert.
  • The webhook URL is never returned to a read-only API key.