Skip to main content

Public & Webhook Routes

These routes require no JWT. Each is protected by its own mechanism — an unguessable workflow UUID, a workflow-scoped API key, or a provider signature — described per route.

Webhook trigger​

POST /webhooks/{workflowId}
GET  /webhooks/{workflowId}

Fires a workflow whose trigger is type: "http". GET is provided for provider ping/verification checks. The request body, headers, and query string become {{trigger.body}}, {{trigger.headers}}, {{trigger.query}} in the DSL.

If the workflow has a webhook_api_key configured (see workflow API keys), requests must include:

X-API-Key: <key>

Security: the workflow ID is a 128-bit UUID — treated as the secret. Add an API key for defense in depth on sensitive workflows.

Synchronous webhook​

POST /webhooks/{workflowId}/sync

Like the standard webhook, but the HTTP request blocks until the workflow execution completes and returns its final output as the response body. Use a webhook_response step to control the status code and body shape — ideal for request/response style integrations (e.g. a custom API endpoint backed by a workflow).

Run a workflow (public API)​

POST /run/{workflowId}
Authorization: Bearer <workflow_api_key>
curl -X POST https://your-instance/run/$WORKFLOW_ID \
  -H "Authorization: Bearer $WORKFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input_field": "value"}'

Independent of the workflow's configured trigger — any workflow can be invoked this way once a public API key has been issued via POST /api/v1/workflows/{id}/api-keys.

Public execution status & files​

GET /public/executions/{id}
GET /public/executions/{id}/stream
GET /public/executions/{id}/files

Lets a frontend embedded outside the dashboard (e.g. a chat widget or /run caller) poll/stream the status of an execution it started, and list any files it produced — without needing a JWT.

Chat deployments​

GET  /public/chat/{slug}
POST /public/chat/{slug}

GET returns the chat widget's public configuration (title, greeting, input_field, output_field). POST sends a user message — the body's input_field key is set to the message text, the workflow runs, and the response's output_field is returned as the assistant's reply. See Deploying Workflows — Chat deployments.

Channel-specific webhooks​

WhatsApp​

GET  /webhooks/whatsapp/{workflowId}    (Meta hub.challenge verification)
POST /webhooks/whatsapp/{workflowId}    (inbound messages — Meta Cloud API or Twilio)

Instagram​

GET  /webhooks/instagram/{workflowId}
POST /webhooks/instagram/{workflowId}

Same verify/receive pattern as WhatsApp, via Meta's webhook infrastructure.

Generated file downloads​

GET /api/v1/files/{id}/{filename}

Public download link for a file generated by a workflow (e.g. a PDF from the pdf node, or an image from image-gen) and explicitly shared. Protected by a 128-bit UUID in the path.

Provider webhooks​

POST /webhooks/stripe     — Stripe billing events, signature-verified (raw body)
POST /webhooks/livekit     — LiveKit room/session events, JWT-signature-verified

These drive billing subscription sync and LiveKit voice agent triggers respectively. Not intended to be called directly — configure these URLs in the Stripe/LiveKit dashboards.

Next​