Workflow trigger delivery

POST

Inbound-email workflow trigger. A mail forwarder POSTs a parsed email as JSON. Path: POST /api/workflows/triggers/email/{token}. A migrated trigger answers 410 past its grace window and carries a Deprecation response header.

Authorizations

• webhook_token
• webhook_hmac

Request Body^required

Media typeapplication/json

The generic webhook / trigger delivery body: an arbitrary JSON object the caller posts. SupaCloud does not impose a fixed shape — the whole object is handed to the workflow run as the trigger context (SC_TRIGGER_CONTEXT). This is an honest record-of-unknown, NOT a fake structure: the runtime never deserializes it into named fields.

object

key

additional properties

Arbitrary trigger payload fields, forwarded verbatim to the run as SC_TRIGGER_CONTEXT. Flattened so the component IS the open object the caller posts (not a wrapper); the runtime never deserializes named fields.

Example^generated

{
  "additionalProperty": "example"
}

Responses

200

Delivery accepted (fired or skipped).

Media typeapplication/json

The standard webhook ack body returned by SupaCloud’s own trigger receivers: { "status": "fired" | "skipped" | "gone", "run_id": "<uuid>"?, "reason": "<text>"? }. A receiver acks (200) even on a filtered-out delivery so the sender does not disable the hook; run_id is present only when a run was started.

object

reason

Why a delivery was skipped or is gone — present for skipped / gone.

string | null

run_id

The started workflow run id — present only when status = "fired".

string | null format: uuid

status

required

fired (a run started), skipped (authenticated but filtered out) or gone (a migrated email trigger past its grace window).

string

Example^generated

{
  "reason": "example",
  "run_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status": "example"
}

400

Malformed body (non-JSON / rejected content-type).

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Invalid or missing HMAC signature.

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Forbidden (issue-debate fail-closed gate / disabled automation switch).

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

404

Unknown trigger token.

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null

null

object

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

410

Email trigger migrated past its grace window (email receiver only).

Media typeapplication/json

The standard webhook ack body returned by SupaCloud’s own trigger receivers: { "status": "fired" | "skipped" | "gone", "run_id": "<uuid>"?, "reason": "<text>"? }. A receiver acks (200) even on a filtered-out delivery so the sender does not disable the hook; run_id is present only when a run was started.

object

reason

Why a delivery was skipped or is gone — present for skipped / gone.

string | null

run_id

The started workflow run id — present only when status = "fired".

string | null format: uuid

status

required

fired (a run started), skipped (authenticated but filtered out) or gone (a migrated email trigger past its grace window).

string

Example^generated

{
  "reason": "example",
  "run_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "status": "example"
}