ConnectCloud Developers

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); field names the first invalid field, details.fields every 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 call
  • runId (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}'

View as Markdown · Interactive reference · OpenAPI