---
title: "Workflows and custom actions"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/workflows.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Workflows and custom actions

Build durable server-side automations from native actions, approvals, waits, webhooks, AI actions, and extension services.

## In brief

- **Execution:** Server-side
- **Published runs:** Snapshot configuration
- **Extensibility:** Native + webhook + container actions

Workflows are BuildWithHQ's server-side orchestration layer. They let a builder connect application events to durable sequences of actions without pushing business logic into a browser.

## Workflow lifecycle

1. **Draft** a definition and add ordered steps.
2. **Validate and publish** the definition.
3. **Trigger a run** manually, from record activity, on a schedule, or from another approved source.
4. **Snapshot the steps** into the run so later edits cannot change an in-flight execution.
5. **Workers claim work** with leases, execute one step at a time, and record outcomes.
6. **Wait, pause for approval, continue, fail, or cancel** without losing the run history.

## Built-in step families

The workflow model supports step families such as notifications, record updates, assignments, tags, follow-ups, messages, billing actions, waits, human approvals, AI actions, and outbound webhook calls. Custom container-backed actions can extend that list without moving the workflow engine into the customer container.

## Failure policy belongs to the step

A step can define what the run should do when execution fails: stop the run, skip the failed step, or continue according to the workflow's policy. That makes failure behavior part of the automation definition rather than an undocumented worker decision.

## Custom actions

A reusable custom action should declare a stable key, display name, input schema, output schema, required permissions/connections, execution target, and optional outcome branches. The builder UI can then render the configuration form from that contract while the runtime validates it again at execution.

```
{
  "key": "company.enrich",
  "inputSchema": {},
  "outputSchema": {},
  "requiredPermission": "records.write",
  "execution": {
    "type": "containerEndpoint",
    "endpointKey": "company.enrich"
  }
}
```

Note

The current generated public v1 OpenAPI contract does not expose workflow-definition or workflow-run endpoints. Use the Builder/tenant workflow surfaces today; do not invent REST paths from this conceptual lifecycle.

Tip

Treat a published workflow as executable application logic. Version it, test it, and keep its inputs/outputs as explicit as an API endpoint.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/workflows.html).