# Trigger Workflow Webhook

`POST /workflows/{wflId}/webhook` · Core · Compute & Automation

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

| Name | In | Required | Description |
|---|---|---|---|
| `wflId` | path | yes | The workflow's id (`wfl_...`). Example: `"wfl_demo00000001"`. |
| `x-k9o-timestamp` | header | yes | When the request was signed, as Unix seconds. It must be within 5 minutes of the server's clock. |
| `x-k9o-signature` | header | yes | 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 | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

## Responses

- **202**: Accepted

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes |  |
| `data.id` | string | yes | The run id (`wfr_...`). |
| `data.workflowId` | string | yes | The workflow that was fired (`wfl_...`), as given in the path. |
| `data.projectId` | string | yes | The project (`proj_...`). |
| `data.status` | enum ("pending", "running", "succeeded", "failed", "cancelled") | yes | 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. |
| `data.triggerContext` | object | yes | How the run was started: `{trigger: "webhook"}`. The body you posted is the run's input and is never returned. |
| `data.perStepStatus` | array of object | yes | One entry per step that has started, in the order they started. Empty for a pending run. |
| `data.perStepStatus.[]step_index` | integer | no | The step's index in the workflow. |
| `data.perStepStatus.[]action_type` | string | no | What the step does. |
| `data.perStepStatus.[]status` | string | no | `running`, `retrying`, `succeeded`, `skipped` (its condition was false) or `failed`; or `awaiting_<what>` while the run waits, such as `awaiting_approval`. |
| `data.perStepStatus.[]attempt` | integer | no | The attempt number of a retried step; 0 otherwise. |
| `data.perStepStatus.[]started_at` | string (date-time) | no | When the step started. |
| `data.perStepStatus.[]completed_at` | string (date-time) | no | When the step finished. |
| `data.perStepStatus.[]parked_at` | string (date-time) | no | When the step began waiting. |
| `data.perStepStatus.[]retry_at` | string (date-time) | no | When a retrying parallel step tries again. |
| `data.perStepStatus.[]last_reason` | string | no | Why the last attempt of a retrying step failed. |
| `data.perStepStatus.[]output_summary` | object | no | A short summary of what the step did, such as a row count. It never holds the step's full output. |
| `data.perStepStatus.[]error` | object | no | Why the step failed. Present on a failed step. |
| `data.perStepStatus.[]error.code` | string | yes | The error code. |
| `data.perStepStatus.[]error.reason` | string | yes | A fixed reason word. |
| `data.costAccountingTotal` | number | yes | The run's metered cost. |
| `data.errorContext` | object | yes | Why the run failed. Null unless the run failed. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.startedAt` | string (date-time) | yes | When the run was created. |
| `data.completedAt` | object | yes | When the run ended. Null while it is pending or running. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.firedBy` | enum ("system.webhook") | yes | Always `system.webhook`: the run was started by a signed webhook, not by a person. |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_WORKFLOW_WEBHOOK_SIGNATURE_INVALID` | The HMAC-SHA256 signature on the webhook request did not match the workflow's secret, or the signature header was absent. |
| 404 | `K9O_WORKFLOW_NOT_FOUND` | No workflow with the supplied ID exists in this project. |

## Code samples

### cURL

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

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/workflows/wfl_demo00000001/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/trigger-workflow-webhook
