Start a flow from an inbound webhook (public; the token is the credential)
POST /api/flows/v1/hooks/{token}
Module: Flows · operationId: receiveFlowWebhook · Tag: Runs · Auth: none
The JSON body (at most 1 MiB) becomes trigger.data. A webhook with auth: hmac also needs the header
X-Flows-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)> (401 invalid_signature); the key is the
secret exactly as shown at publish or rotation (its characters, not hex-decoded). Needs no access token: the
token in the path is the credential – keep it secret like an API key. Content-Type must be
application/json (415 unsupported_media_type). An unknown token, or a flow that is archived or not
published, answers 404; a disabled one 409 flow_disabled. With an
Idempotency-Key header a repeated call answers the same run (created: false). A trigger filter that is false
starts nothing (runId null). A flow started more than 60 times in a minute pauses (409 flow_tripped).
Rate-limited per client IP.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key |
header | string | (max length 200) | |
X-Flows-Signature |
header | string | ||
token |
path | string | yes | (max length 128) |
Request body
application/json (required)
Example:
{
"currency": "EUR",
"customer": "Alpenhotel Seeblick GmbH",
"event": "order.created",
"orderNo": "SO-10482",
"total": 1249.9
}
Responses
- 202 Accepted (
application/json) - 400 Invalid input (
invalid);fieldnames the first invalid field,details.fieldsevery one. (application/json) - 401 invalid_signature (
application/json) - 404 The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (
application/json) - 409 The state does not allow it: version_conflict (reload), no_changes, archived, key_taken, flow_disabled, flow_tripped, task_closed, run_finished. (
application/json) - 413 too_large (
application/json) - 415 unsupported_media_type (
application/json) - 422 invalid_definition (details.diagnostics), permission_missing (details.groups), owner_inactive, owner_not_found, not_published, key_changed, not_webhook, filter_failed, unknown_trigger, no_manual_trigger. (
application/json) - 429 Too many calls from this address
Fields of the 202 answer:
created(boolean, required): False when an Idempotency-Key repeated an earlier callrunId(string (uuid), nullable, required): The started run; null when the trigger's filter did not hold
Example 202 answer:
{
"created": true,
"runId": "4a6c8e0b-2d4f-4b6a-8c9e-1f3a5c7e9b0d"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/hooks/string' \
-H 'Content-Type: application/json' \
--data '{"currency":"EUR","customer":"Alpenhotel Seeblick GmbH","event":"order.created","orderNo":"SO-10482","total":1249.9}'