Webhook trigger

The API/Webhook Trigger gives your workflow an HTTPS URL. A request to that URL starts a run, with the request body, headers and query string as trigger data.

When to use it

• Receiving events from a service that has no Flero connector, such as an internal system.
• Receiving events from a service whose connector has no event trigger for what you need.
• Turning a workflow into an HTTP endpoint that returns a result.

If the service has a connector event trigger, prefer it. Push connector triggers register their URL with the provider and verify each delivery for you.

Configuration

Paths are shared across your Flero instance. Webhooks are routed by path alone. Give each webhook a distinct path, for example by prefixing it with the team or system name.

Request bodies

• An empty body starts one run with an empty payload.
• A JSON object starts one run.
• A JSON array starts one run per object in the array. Elements that are not objects are skipped.
• A body that is not valid JSON gets 400 Invalid JSON payload. Send JSON: form-encoded and multipart bodies are not parsed.

The trigger data

Inside the workflow, read the request through $trigger:

The trigger node's own output carries the same fields (payload, headers, query, method, path) plus triggeredAt and payloadType. The secret is never included.

Activating the webhook

1. Save the workflow.
2. Set the workflow to Active in the editor toolbar's version menu.
3. Copy the URL from the trigger's inspector.
4. Configure the external service to send requests to that URL.

The webhook always runs the workflow's active version. While the workflow is inactive, the URL answers 404 Webhook not found.

Testing

Send a test request with curl once the workflow is active:

curl -X POST https://acme.flero.ai/trigger/orders/created \
  -H "Content-Type: application/json" \
  -d '{"orderId": 42, "amount": 99.99}'

Open the run in the execution history to see what arrived.

Security

Use a secret

Anyone who knows the URL can start the workflow. Set a Secret Key to require a signature on every request.

The secret is an HMAC key, not a password to send. The caller computes HMAC-SHA256 of the raw request body, keyed with the secret, and sends the hex digest in one of these headers:

• X-Hub-Signature-256
• X-Webhook-Secret

Both sha256=<hex> and a bare <hex> are accepted. A missing signature gets 401 Missing webhook signature. A wrong one gets 401 Invalid webhook signature.

BODY='{"orderId": 42}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST https://acme.flero.ai/trigger/orders/created \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  -d "$BODY"

GitHub signs its webhooks this way, with X-Hub-Signature-256, so a GitHub webhook secret works as the Secret Key.

Other signing schemes

Services such as Stripe or Shopify sign with their own header and format. Flero does not check those. Verify them inside the workflow, for example with a Code node that recomputes the signature, followed by an If node that stops the run on a mismatch.

CORS

The webhook answers browser preflight requests and allows any origin. Treat a browser-called webhook as public and use a secret or a check inside the workflow.

Response modes

Immediate

Flero starts the runs and answers 202 Accepted at once:

{
  "success": true,
  "executionId": "exec_...",
  "executionIds": ["exec_..."],
  "workflowId": "...",
  "message": "Workflow execution triggered"
}

The caller does not get the workflow's result. This suits most webhooks.

Wait

Flero runs the workflow and answers 200 when it finishes, with each run's result:

{
  "success": true,
  "executionId": "exec_...",
  "executionIds": ["exec_..."],
  "workflowId": "...",
  "results": [{ "executionId": "exec_...", "status": "success", "data": {} }]
}

The status is 200 even when a run fails. Check each results[].status. With an array body, the runs execute one after another. Use Wait for short workflows that act as an API endpoint.

Tips & gotchas

• The URL changes when the path changes. Update the calling system when you rename the path.
• Duplicate deliveries all run. The webhook does not deduplicate. If the sender retries, make the workflow safe to run twice, for example by checking an event id first.
• One method per trigger. To accept GET and POST on the same workflow, add two webhook triggers with different paths.
• Arrays fan out. A sender that batches events in a JSON array starts one run per event.

Related

• Connector event triggers: push events from connected services
• Manual & test runs: start a run through the Flero API instead
• Common patterns

Found something out of date? This page lives in the Flero docs content set.