API route trigger

The API route type exposes an HTTP access point: each valid request triggers the associated workflow by passing it the request (method, headers, body, …).

Webhooks

A webhook — mechanism by which an external service sends events over HTTP — is configured with this type: there is no separate "Webhook" trigger type. Choose the POST method (often imposed by the provider) and a dedicated path (e.g. /webhooks/stripe), deploy, then register the full URL provided by Ecosystem in the third-party service console.

Parameters

Parameter	Type	Required	Default	Description
Name	String	✅	—	Trigger label; automatically pre-fills the Path (slug).
Path (slug)	String	✅	—	URL identifier, pre-filled from the Name, editable.
HTTP methods	List	✅	—	Accepted methods: GET, POST, PUT, DELETE, PATCH, HEAD (one or more).
Path	String	❌	—	Additional endpoint path (Custom Path), with possible dynamic parameters.
Headers	Key-value pairs	❌	—	Headers expected on incoming requests.
Expected response format	example / JSONSchema	❌	—	Expected response contract for the API consumers.

Customize the Path

The Path (Custom Path) field defines the HTTP path exposed in addition to the slug. The public URL combines the slug and the path:

https://<environment>/<slug><path>

Element	Example	Role
Slug	api.reception.commandes	Identifies the trigger in Ecosystem
Path	/orders/:id	Additional route, with possible parameters
Full URL	…/api.reception.commandes/orders/1234	Request received by the trigger

The syntax follows the Express.js routing conventions:

Syntax	Example of path	Effect
Fixed segment	/orders	Matches this path exactly
Parameter :name	/order/:id	Captures a segment in incomingRequest.params.name
Optional parameter :name?	/:id?	Accepts the request with or without this segment
Wildcard *name	/orders/*path	Captures the rest of the path after the prefix

Fixed segment — a path without parameter matches the requested URL exactly (excluding the query string):

Configured path	Accepted request	Rejected request
/orders	POST /orders	POST /orders/42
/webhooks/stripe	POST /webhooks/stripe	POST /webhooks/stripe/events

Custom parameter (:name) — a segment prefixed with : captures a variable value, exposed in incomingRequest.params:

Request	Captured value
GET /order/1234	incomingRequest.params.id → '1234'
GET /order/abc-def	incomingRequest.params.id → 'abc-def'

// For a GET /order/1234 request
incomingRequest.params.id // '1234'

An id column is added automatically in the trigger's data views.

Optional parameter (:name?) — add ? after the parameter name to make it optional:

Request	Captured value
GET /1234	incomingRequest.params.id → '1234'
GET /	incomingRequest.params.id → undefined

// GET /1234 request
incomingRequest.params.id // '1234'

// GET / request (empty path)
incomingRequest.params.id // undefined

Useful for a single endpoint that handles both an identified resource and a collection.

Wildcard (*name) — *name accepts the rest of the path after a fixed prefix; the captured portion is a string (segments separated by /):

Request	Captured value
GET /orders/1234/delivery	incomingRequest.params.path → '1234/delivery'
GET /orders/a/b/c	incomingRequest.params.path → 'a/b/c'

// GET /orders/1234/delivery request
incomingRequest.params.path // '1234/delivery'

Suitable for "catch-all" APIs: proxy, nested files, routes whose depth varies.

Path best practices

• Prefix the paths with a version or a business domain: /v1/orders/:id rather than /:id.
• Validate incomingRequest.params in the workflow (presence, format, allowed values), especially for optional parameters (undefined).
• Query strings (?foo=bar) are not part of the path: use incomingRequest.query.
• Avoid wildcards that are too broad in production.

Input data example

The Example section of the form describes the schema or example of the data the trigger is expected to receive:

{
  "orderId": "CMD-4821",
  "customer": { "id": "CUS-77", "email": "customer@example.com" },
  "total": 149.9
}

This section serves as a reference for integrators who call your trigger. If validation is enabled and the received data does not comply with the schema, the workflow does not start and an error is returned. The example can be deduced from an imported Swagger file or entered manually.

By enabling data validation, an interface allows defining, for each field, its validation schema:

Field	Description
Name	Field name.
Description	Description of the expected field.
Example	Example value for the field.
Type	Expected type: string, number, boolean, object, array, integer.
Hide	Hides the field (e.g. password, secret).
Required	Indicates whether the field is mandatory.

Input

The trigger receives the full HTTP request: method, path, query string, headers and body.

{
  "method": "POST",
  "url": "https://api.example.com/api.reception.commandes/orders/1234?lang=fr",
  "query": { "lang": "fr" },
  "params": { "id": "1234" },
  "headers": { "content-type": "application/json" },
  "body": { "orderId": "CMD-4821", "total": 149.9 }
}

Output

The workflow accesses the request body via data, and the metadata via incomingRequest:

Property	Description
data	Request body, parsed as JSON.
incomingRequest.method	HTTP method of the request.
incomingRequest.url	Full request URL.
incomingRequest.query	Query string parameters.
incomingRequest.params	Captured path parameters (:id, :id?, *path).
incomingRequest.headers	Received HTTP headers.

From a following node: {{data.orderId}} or {{incomingRequest.params.id}}.

Errors

• Rejected request — a path that does not match the configured pattern (fixed segment, parameter, wildcard) does not start the workflow: the request is rejected.
• Missing optional parameter — incomingRequest.params.id is undefined: validate its presence in the workflow before using it.

Example

Order reception: create an API route trigger (method POST, path /orders), associate a workflow that validates the body then processes the order, and deploy. Each POST /orders starts the workflow.

Consult an order: create a GET trigger with path /orders/:id; the workflow reads incomingRequest.params.id, loads the order and answers via an HTTP Response node.

See also

• Trigger node — received data and access to incomingRequest
• Authentication methods
• Usage patterns
• Other trigger types