HTTP Request Trigger

The HTTP Request trigger puts a flow behind a URL you define: you pick a gateway, type a path, and POSTs to that address run the flow. The request body becomes $.trigger, and the flow’s result comes back to the caller. It is the same machinery as the Webhook trigger, with the settings exposed and the endpoint authenticated from the start.

Creating one

Add an HTTP Request trigger from the Add Node panel. A dialogue opens:

Field	Default	Notes
Public URL	Off	On means no authentication at all
Gateway	Your only gateway	Shown when the account has more than one
URL Path	Empty, placeholder `/example/path`	Yours to choose, leading slash included
Invocation Type	Request/Response	`Asynchronous` returns as soon as the run starts
Timeout	30	Seconds
Requests / Second	100	Under Request Limits

Press Create. Everything except the path and the gateway can be changed later from the trigger node.

There is no method setting. The endpoint accepts POST.

The URL

https://<your-gateway-host><your-path>

<your-gateway-host> is your own gateway’s hostname — a subdomain of the platform’s API host, unique to that gateway. It is not api.quiva.ai, and there is no /flows/<id>/trigger route. The trigger node shows the finished address on a Full URL row with a Copy button. Use that; do not assemble the URL from parts.

Calling it

curl -X POST "https://<your-gateway-host>/orders/intake" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"order_id":"ord_88","customer":{"email":"dana@example.com"},"total":35}'

The authentication header is x-api-key. There is no query-string form. Keys issued from a trigger panel are restricted keys — they carry an msr- prefix and are valid for that one endpoint and method only. A body that is present must be valid JSON. One that fails to parse is rejected with 400 and a JSON error body:

{
  "error": "invalid_request_body",
  "message": "Request body must be valid JSON",
  "details": { "resource": "…", "reason": "unexpected end of JSON input" }
}

Every other failure at the endpoint is statused the same way — 400 for a body that cannot be read, 500 for an internal encoding failure, 504 when the flow does not answer inside the mapping’s timeout, and 502 when it answers with nothing. Form-encoded (application/x-www-form-urlencoded) and multipart bodies are not JSON and are rejected as such. An empty body is allowed. A request with no body at all starts the run with $.trigger set to null — useful when everything the flow needs is in the path or the query string.

Security

The endpoint is authenticated by default — the help text on the toggle reads “If set will expose the URL to the public without any need for authentication.”, and it starts off. To issue a key, open the trigger node, expand Security, set Expiry (days) (365 by default), and press Generate API Key. The key is shown once and is scoped to this endpoint alone. There is no regenerate button. Rotating means deleting the key and generating a new one, which invalidates the old one immediately.

Allowed Hosts

The Allowed Hosts section on the trigger node edits your account’s gateway CORS allowlist. It is what lets a browser on your own site call the endpoint.

This list belongs to the gateway, not to the trigger. Every endpoint on that gateway shares it — two triggers cannot have different allowlists.

Reading the request

$.trigger is the raw request body. Nothing is wrapped around it and nothing is added. For the body above:

Expression	Resolves to
`$.trigger.order_id`	`"ord_88"`
`$.trigger.customer.email`	`"dana@example.com"`
`$.trigger.total`	`35`
`$.trigger`	the whole body

Request headers are on $.env.headers, flattened to strings:

$.env.headers["Content-Type"]
$.env.headers["User-Agent"]

Two different casings live in this map. A header the caller sent arrives in canonical form — Content-Type, User-Agent, X-Api-Key — because Go’s HTTP server normalises it on the way in. A header the platform added for you is lower-case: x-method, x-url, x-account-id and every x-param-*. Nothing after the gateway re-cases either, so match what you see here exactly.

$.env.auth_token holds the bearer token the call carried, and $.env.run_id the run’s tracking ID.

Query and path parameters

The query string and the path’s own parameters arrive as headers, alongside the ones the caller sent:

Source	Read it at
`?status=paid`	`$.env.headers['x-param-query-status']`
An `{id}` segment in the URL Path	`$.env.headers['x-param-id']`
The request method	`$.env.headers['x-method']`
The path the call arrived on	`$.env.headers['x-url']`

Values are strings. A parameter repeated in the query string — ?tag=a&tag=b — arrives as one comma-joined value, "a,b"; split it in a Map or Eval step if you need the parts. A parameter that was not sent is absent, and reading an absent path resolves to []. The header takes the parameter’s name exactly as written, so a {order_id} segment lands at x-param-order_id. x-method is always POST for a trigger created from the flow editor, because the mapping is created for that one method. It becomes useful only if you point a second mapping with a different Method at the same flow from Resources → Gateways.

A path that matches nothing resolves to an empty array, not null. $.trigger.missing becomes [].

The response

Request/Response

The caller waits for the flow to finish and receives:

{
  "tracking_id": "…",
  "status": "…",
  "result": { }
}

By default result carries every step’s output. To return a specific shape, open the flow’s Final Response Mapping and give it a JSONPath object — result then becomes exactly that:

{
  "order_id": "$.trigger.order_id",
  "decision": "$.CHECK_STOCK.status",
  "message": "Order |$.trigger.order_id| accepted"
}

Asynchronous

The caller gets a reply the moment the run is accepted:

{ "tracking_id": "…" }

The flow continues in the background. Nothing is sent back when it finishes — track it in Monitoring, or have a step call the caller back.

There is no executionId, no executionTime, no 202 Accepted and no error.code envelope. A run that errors returns the same shape, with the failure in status.

A Timeout shorter than the flow’s runtime cuts the caller off with a 504. If the flow is slow, either raise the timeout or switch Invocation Type to Asynchronous.

Draft and published flows

An HTTP Request trigger always runs the published flow. The mapping is created against the published subject even when you build it on a draft.

Before the flow’s first publish, there is nothing at the other end of the URL.
Save does not change what the endpoint executes. Publish does.

To exercise a draft, use the flow editor’s Test control, which runs the draft against a JSON payload you type.

What runs after the trigger is decided by each step’s outcome, not by the arrows in the editor. A Condition step’s outcome names the step IDs to run next — one, several (they start at the same time), or the reserved RESOLVE_SUCCESS / RESOLVE_ERROR to end the run. A line drawn between two steps that no outcome names is decoration.

Troubleshooting

400 invalid_request_body

The body is not valid JSON. details.reason carries the parser’s own message. Send no body at all if you have nothing to send — that is accepted.

401 or 403

The endpoint is not public and the call is missing x-api-key, or the key has expired.

504 Gateway Timeout

The mapping’s Timeout is in seconds and defaults to 30. Raise it, or switch to Asynchronous and stop waiting.

A query parameter is not arriving

It is not on $.trigger — it is on $.env.headers['x-param-query-<name>']. Check the name’s case: the header is built from the parameter exactly as the caller spelled it.

502 flow_no_response or 504 flow_invocation_timeout

504 means the flow did not finish inside the mapping’s Timeout; raise it or switch to Asynchronous. 502 means the run produced no reply at all — look for the run in Monitoring.

A browser call is blocked by CORS

Add the origin under Allowed Hosts. Remember that it is shared across the whole gateway.

The response contains far more than expected

With no Final Response Mapping set, result is every step’s output. Set one.

Changes to the flow are not reflected

The endpoint runs the published flow. Press Publish.

Next Steps

Webhook Trigger

The same endpoint with a generated path

Embed Triggers

Buttons and forms that post to this endpoint

Variable Mapping

Reading the request body in later steps

Triggers Overview

Every way a flow can start

Get Started

Spaces

Meetings

Forms

Assistants

Collaboration

Flows

Account Management

Advanced

Developers

HTTP Request Trigger

HTTP Request Trigger

Creating one

The URL

Calling it

Security

Allowed Hosts

Reading the request

Query and path parameters

The response

Request/Response

Asynchronous

Draft and published flows

Troubleshooting

Next Steps

Webhook Trigger

Embed Triggers

Variable Mapping

Triggers Overview

​HTTP Request Trigger

​Creating one

​The URL

​Calling it

​Security

​Allowed Hosts

​Reading the request

​Query and path parameters

​The response

​Request/Response

​Asynchronous

​Draft and published flows

​Troubleshooting

​Next Steps

Webhook Trigger

Embed Triggers

Variable Mapping

Triggers Overview

HTTP Request Trigger

Creating one

The URL

Calling it

Security

Allowed Hosts

Reading the request

Query and path parameters

The response

Request/Response

Asynchronous

Draft and published flows

Troubleshooting

Next Steps