## 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:

```json
{
  "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:

```json
{
  "created": true,
  "runId": "4a6c8e0b-2d4f-4b6a-8c9e-1f3a5c7e9b0d"
}
```

### Example request

```bash
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}'
```
