Skip to main content
POST/workflows/{wflId}/webhook

Trigger Workflow Webhook

Fires a workflow whose trigger_type is webhook by posting to its dedicated webhook endpoint.

The request is anonymous-authenticated.

The caller must supply a valid HMAC-SHA256 signature if the workflow's signatureScheme is hmac-sha256; workflows configured with signatureScheme: 'none' require no signature.

Returns K9O_WORKFLOW_WEBHOOK_SIGNATURE_INVALID (401) if signature verification fails.

Parameters
wflId *path

The workflow's id (wfl_...).

x-k9o-timestamp *header

When the request was signed, as Unix seconds.

It must be within 5 minutes of the server's clock.

x-k9o-signature *header

The hex HMAC-SHA256 of <x-k9o-timestamp>.<raw body>, keyed with the workflow's webhook secret.

A signature that has been used before is refused.

Every refusal, including a wrong signature, a stale timestamp and an unknown workflow, is the same 401 K9O_WORKFLOW_WEBHOOK_SIGNATURE_INVALID.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
Responses
HTTPK9O CodeDescription
202Accepted
401K9O_WORKFLOW_WEBHOOK_SIGNATURE_INVALIDThe HMAC-SHA256 signature on the webhook request did not match the workflow's secret, or the signature header was absent.
404K9O_WORKFLOW_NOT_FOUNDNo workflow with the supplied ID exists in this project.
Response body (202)
data *object
id *string

The run id (wfr_...).

workflowId *string

The workflow that was fired (wfl_...), as given in the path.

projectId *string

The project (proj_...).

status *"pending" | "running" | "succeeded" | "failed" | "cancelled"

The run's state when the answer was read.

It is pending until the runner picks the run up, normally at once, and may already be running or finished.

Runs of one workflow go one at a time.

triggerContext *any

How the run was started: {trigger: "webhook"}.

The body you posted is the run's input and is never returned.

perStepStatus *object[]

One entry per step that has started, in the order they started.

Empty for a pending run.

step_indexinteger

The step's index in the workflow.

action_typestring

What the step does.

statusstring

running, retrying, succeeded, skipped (its condition was false) or failed; or awaiting_<what> while the run waits, such as awaiting_approval.

attemptinteger

The attempt number of a retried step; 0 otherwise.

started_atstring <date-time>

When the step started.

completed_atstring <date-time>

When the step finished.

parked_atstring <date-time>

When the step began waiting.

retry_atstring <date-time>

When a retrying parallel step tries again.

last_reasonstring

Why the last attempt of a retrying step failed.

output_summaryobject

A short summary of what the step did, such as a row count.

It never holds the step's full output.

errorobject

Why the step failed.

Present on a failed step.

code *string

The error code.

reason *string

A fixed reason word.

costAccountingTotal *number

The run's metered cost.

errorContext *any

Why the run failed.

Null unless the run failed.

One of: object
or: null
startedAt *string <date-time>

When the run was created.

completedAt *any

When the run ended.

Null while it is pending or running.

One of: string <date-time>
or: null
firedBy *"system.webhook"

Always system.webhook: the run was started by a signed webhook, not by a person.

meta *any
cURL
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/workflows/wfl_demo00000001/webhook' \
  -H 'Content-Type: application/json' \
  -d '{}'

Showing example in cURL

Request example
Response example (202)
{
  "data": {
    "id": "string",
    "workflowId": "string",
    "projectId": "string",
    "status": "pending",
    "perStepStatus": [
      {
        "step_index": 0,
        "action_type": "string",
        "status": "string",
        "attempt": 0,
        "started_at": "string",
        "completed_at": "string",
        "parked_at": "string",
        "retry_at": "string",
        "last_reason": "string",
        "error": {
          "code": "string",
          "reason": "string"
        }
      }
    ],
    "costAccountingTotal": 0,
    "startedAt": "string",
    "completedAt": "string",
    "firedBy": "system.webhook"
  }
}

More in Compute & Automation