> For the complete documentation index, see [llms.txt](https://docs.hexabot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hexabot.ai/workflow-editor/workflow-types/manual-workflows-http-webhooks-and-api-triggers.md).

# Manual Workflows: HTTP Webhooks and API Triggers

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

<figure><img src="/files/A9rasXlAJn0JUyjh7Ae0" alt="Hexabot manual workflow webhook endpoint and input schema settings"><figcaption></figcaption></figure>

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**

```bash
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:

```bash
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.

```json
{  "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

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

flow:
  - do: lookup_order
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hexabot.ai/workflow-editor/workflow-types/manual-workflows-http-webhooks-and-api-triggers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.