JustFlows docs

Guide

Public webhook API

A workspace can expose a published workflow through a generic webhook trigger. The flow builder supplies the trigger's public ID and secret.

Start a run

curl -X POST "https://your-domain.example/api/v1/webhooks/PUBLIC_ID" \
  -H "Authorization: Bearer WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: order-1234" \
  -d '{"customer_id": 42, "event": "order.created"}'

The secret may instead be sent in X-JustFlows-Webhook-Secret. A valid request returns HTTP 202 with the flow run ID, trigger event ID, current status, and a run_status_url.

Read run status

curl "https://your-domain.example/api/v1/webhooks/PUBLIC_ID/runs/RUN_ID" \
  -H "X-JustFlows-Webhook-Secret: WEBHOOK_SECRET"
StatusMeaning
200The requested run belongs to this webhook and its status was returned.
202The webhook was accepted and the run was started.
401The webhook secret is missing or invalid.
404The trigger is missing/inactive, or the run does not belong to it.
422The event was received but a workflow run could not be started.
  • Store the secret in a secret manager and rotate it if exposed.
  • Use a stable, unique X-Request-Id for tracing.
  • Treat 202 as asynchronous acceptance, not completed work.
  • Set upstream timeouts and retries appropriate for an asynchronous endpoint.
  • Deactivate the trigger before deleting or replacing an external integration.