Manual Workflows: HTTP Webhooks and API Triggers

Create on-demand Hexabot automations with manual workflow triggers, HTTP webhooks, API calls, authentication, and custom JSON input schemas.

Manual workflows are reusable Hexabot automations that run on demand. Trigger them from the admin UI simulator or an external application through an HTTP API webhook.

Use manual workflows for API-driven automation, custom integrations, and one-off administrative tasks. Define a custom JSON input schema for every manual workflow.

Configure a manual workflow webhook endpoint and input schema

When creating or editing a Manual workflow, you can:

• Expose the workflow through an HTTP webhook so external applications can trigger it.

• Define the structure of the input accepted by the workflow.

These settings are available in the Webhook Endpoint and Input Schema sections of the workflow form.

Expose a manual workflow as an HTTP webhook

Enable Enable endpoint to create an HTTP webhook endpoint for the manual workflow.

For a new workflow, save it first. The Webhook Trigger URL becomes available after the workflow has been created. You can then copy the URL or use the code button to view a request example.

Trigger the workflow by sending a POST request to this URL:

<HEXABOT_API_URL>/api/webhook/<WORKFLOW_ID>/trigger

The request must contain a JSON object. The complete JSON request body is passed to the workflow as its input.

Disabling the endpoint prevents external services from triggering the workflow through this URL.

Configure webhook authentication

Choose how incoming webhook requests are authenticated.

Authentication	Configuration
None	Does not require authentication. Anyone with the URL can trigger the workflow. Use this option only in trusted or development environments.
Basic Auth	Define a username and select a credential containing the expected password.
Header Auth	Define a request header and select a credential containing its expected value. The default header name is X-Webhook-Token.
JWT Auth	Select a signing algorithm and a credential containing the signing secret. After saving the workflow, generate a token and send it as a Bearer token.

When an endpoint is enabled for the first time, Hexabot selects Header Auth by default to reduce the risk of accidentally exposing an unauthenticated workflow.

Sensitive values are stored as Hexabot credentials rather than directly inside the workflow. Select an existing credential or click Add to create one.

For JWT authentication, generated tokens do not expire automatically. Rotate the signing-secret credential to revoke previously generated tokens.

Header authentication example

curl --request POST "<WEBHOOK_TRIGGER_URL>" \  --header "Content-Type: application/json" \  --header "X-Webhook-Token: <WEBHOOK_TOKEN>" \  --data '{    "raw_signals": {},    "existing_backlog": [],    "approved_for_wordpress_staging": true,    "wordpress_post_status": "draft"  }'

For JWT authentication, provide the generated token using the Authorization header:

curl --request POST "<WEBHOOK_TRIGGER_URL>" \  --header "Content-Type: application/json" \  --header "Authorization: Bearer <JWT_TOKEN>" \  --data '{    "topic": "AI workflow automation"  }'

The webhook request waits for the workflow execution to complete. The response contains the workflow run identifier, final status, output, and any execution error.

{  "runId": "<RUN_ID>",  "status": "<RUN_STATUS>",  "output": {},  "error": null}

Define a custom JSON input schema

Use the Input Schema section to describe the JSON object that the manual workflow accepts.

Click Add property for each expected input field, then provide its name and data type. Properties can use types such as:

• string

• boolean

• number

• object

• array

Object and array properties can be expanded to configure their nested structure.

For example, the following schema describes a workflow that receives content signals and WordPress publishing information:

Property	Type
raw_signals	Object
existing_backlog	Array
approved_for_wordpress_staging	Boolean
wordpress_post_status	String

Before the workflow starts, Hexabot validates the supplied input against this schema. When the payload does not match the expected structure, the request is rejected with an HTTP 400 Bad Request response containing validation details.

The top-level workflow input must be a JSON object. A top-level string, number, or array is not accepted.

Only Manual workflows have a user-editable input schema. Conversational and Scheduled workflows use system-defined input schemas.

Manual workflow YAML example

defs:
  lookup_order:
    kind: task
    action: http_request
    inputs:
      method: GET
      url: "='https://example.com/orders/' & $input.order_id"

flow:
  - do: lookup_order