Inbound

Workflow webhooks

A workflow that starts with a webhook trigger has its own URL. Post JSON to it from any system — a shop, a billing tool, a script — and the workflow runs with that JSON as its input.

Auth: The workflow’s secret
Plan: Automation hub

Set it up

In Nextora, create a workflow and choose the Webhook trigger. The trigger shows the workflow’s URL.
Generate a secret in the trigger’s settings and store it with the sending system. It is shown once; generating a new one replaces it.
Build the steps, using the incoming JSON as {{payload.…}}, and activate the workflow. Inactive workflows refuse calls.

Using the payload

The request is available to every step of the run:

Variable	Holds
`{{payload.…}}`	The JSON body, for example `{{payload.customer.email}}` or `{{payload.total}}`.
`{{headers.…}}`	The request headers, without secrets. Names with hyphens cannot be used in templates.
`{{triggered_at}}`	When the request arrived (UTC).

A body that is not valid JSON reaches the workflow as an empty payload, so send Content-Type: application/json and check the run in the workflow’s history when testing.

Trigger a workflow

POST/api/webhooks/workflow/{workflow_id}

No API key. When the workflow has a secret, send it in x-webhook-secret.

Starts the workflow — and any workflow that subscribes to it — with the request body as payload. The body can be any JSON object.

Path parameters

workflow_iduuidRequired
The workflow’s ID, as in the URL its trigger shows.

Headers

x-webhook-secretstring
The workflow’s secret. Required once a secret is set; a wrong or missing value is refused with 401.
Content-Typestring
application/json.

Returns

200 with the IDs of the workflows that ran. The workflow’s own steps report in its run history, not in this response.

POST/api/webhooks/workflow/{workflow_id}

curl -X POST https://acme.nextora.co/api/webhooks/workflow/4a6c8e0b-2d4f-4b6d-8f0a-6c8e0a2c4e75 \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: whsec_…" \
  -d '{
    "order_id": "SO-1042",
    "customer": {
      "name": "Grace Whitfield",
      "email": "[email protected]"
    },
    "total": 1290,
    "currency": "EUR"
  }'

Response200 OK

{
  "success": true,
  "message": "Workflow triggered successfully",
  "workflow_id": "4a6c8e0b-2d4f-4b6d-8f0a-6c8e0a2c4e75",
  "fired_workflow_ids": [
    "4a6c8e0b-2d4f-4b6d-8f0a-6c8e0a2c4e75",
    "6c8e0a2d-4f6b-4d8f-9a2c-8e0a2c4e6b97"
  ]
}

Responses

These endpoints are outside /api/v1, and their errors are a plain { "error": "…" } object:

Status	Body	Meaning
`200`	`{ "success": true, … }`	The workflow ran.
`400`	`Workflow is not active`	Activate the workflow.
`400`	`Workflow is not configured for webhook trigger`	Its trigger is not a webhook.
`401`	`Invalid webhook secret`	Send the current secret in `x-webhook-secret`.
`403`	`hub_not_in_plan`	Workflows need the Automation hub in the plan.
`404`	`Workflow not found`	Check the ID in the URL.
`503`	`Webhook verification is temporarily unavailable`	Retry with backoff.
`500`	`Internal server error`	Retry with backoff.