Wait for callback `flow.hook`

A hook creates an external boundary that can resolve once. It supports human approval, a UI action, or a webhook callback. The node first commits hook identity and receipt rules, then releases the worker. When valid input arrives, the run is delivered again and the stored payload becomes available. Cancellation or explicit disposal follows a separate branch with no accepted result.

Mode and public boundary

kind selects human approval or webhook behavior. Human approval uses subject and metadata to describe the work. Webhook mode also exposes callback_method and callback_path. When token_expression produces a public receipt credential, derive it from stable data and let the host distribute it through a protected channel. The token is a credential and must stay out of ordinary logs, error messages, analytics, and screenshots.

One accepted receipt opens received control and payload data. A disposed hook, cancellation request, or closed receipt window continues through disposed. The graph should handle both outcomes explicitly. An approval rejection is usually a valid business payload and can be evaluated by a condition after received. Disposal means no result was accepted and should not be presented as a human rejection.

Receipt and security checks

The host endpoint validates token, method, content type, payload size, and caller permission, and it allows only one transition out of waiting state. A duplicate request should return the resolved state or original result, never append different content. Test expired credentials, wrong methods, concurrent receipt, cancellation races, log redaction, and process recovery. Use a signal when messages of the same name must queue and be consumed repeatedly.

Use it for one human approval or external callback. Human mode keeps a subject and metadata; webhook mode also exposes the method and callback path.

Runtime behavior

The node creates a durably identified hook and suspends the run. One valid receipt exposes received and payload; disposal or cancellation selects disposed.

Node contract

Type: flow.hook
Role: Durable runtime command
Runtime binding: create_hook
Durable identity: Graph node ID

Configuration properties

Property	Type and control	Default	Rules
`kind`Callback kind	`tab`TabInput	`human_approval`	Choose what will resume the workflow.Required · Allowed values human_approval, webhook, host_event
`subject`Request title	`str`StrInput	`Review workflow request`	Short title shown in approval queues and audit records.Required
`token_expression`Callback token	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input.callbackToken"}}`	Build a unique token from workflow data. Do not use shared fixed text.Required
`callback_method`HTTP method	`str`DropdownInput	`POST`	HTTP method recorded for the callback route.Optional · Advanced · Allowed values POST, PUT, PATCH · Shown when kind = webhook
`callback_path`Callback path	`str`StrInput	`/callbacks/workflow`	Route provided by the host system. A3S Flow does not serve this path.Optional · Advanced · Shown when kind = webhook
`metadata`Additional metadata	`dict`JSONInput	`{"labels":{},"data":{}}`	Labels and business data saved with the callback.Optional · Advanced

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Input	`token`Token	data	`String`
Input	`metadata`Metadata	data	`JsonValue`
Output	`received`Received	control	`FlowControl`
Output	`payload`Payload	data	`JsonValue`
Output	`disposed`Disposed	control	`FlowControl`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-hook",
  "data": {
    "kind": "human_approval",
    "subject": "Review workflow request",
    "token_expression": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input.callbackToken"
      }
    },
    "callback_method": "POST",
    "callback_path": "/callbacks/workflow",
    "metadata": {
      "labels": {},
      "data": {}
    },
    "type": "flow.hook"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node flow.hook --pretty
a3s-flow new flow.hook --id example-flow-hook --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "flow.hook" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Treat callback tokens as credentials and keep them out of logs.
One hook can be received or disposed only once.
A cancellation request disposes hooks that are still waiting.

#Wait for callback flow.hook

#Mode and public boundary

#Receipt and security checks