Webhook node

A webhook node calls an external HTTP service and makes the response available to the rest of your workflow. Each node can send directly from Docana or through a Brazil or US relay. Existing nodes keep sending directly until you change their route.

Choose an outbound route

Open the webhook node in the agent's flow and choose its outbound route. The choice is saved with that node, so different calls in one workflow can use different routes.

Selection	AgentSpec value	Behavior
Direct	"direct" or omitted	Send from the platform using the existing direct connection.
Brazil	"brazil"	Send through the Brazil relay.
US	"us"	Send through the US relay.

Regional placement is not a guarantee of a fixed outbound IP address or country. A destination may still reject the request. If a selected relay is unavailable, the call fails on that route. Docana does not silently retry it through another region or a direct connection.

The destination URL, method, headers, query parameters, and body work the same way on each route. Response decoding and downstream variables also stay the same. Public HTTP and HTTPS destinations are supported.

Set the route in a spec

Set proxy inside the webhook node's config. The value is a literal choice, not a template or a relay URL.

{
  "id": "fetch-report",
  "type": "action",
  "actionType": "WEBHOOK",
  "mode": "sync",
  "config": {
    "url": "https://example.com/report.pdf",
    "method": "GET",
    "proxy": "brazil",
    "responseMode": "text"
  },
  "outputVar": "report",
  "transition": []
}

This example sends the request through the Brazil relay and exposes the extracted report text to downstream nodes. Use "us" for the US relay. Remove proxy or set it to "direct" to return to the direct route.

Pull the agent with docana agents pull <agent-id> -o agent.json, edit the node, then run:

docana agents validate agent.json
docana agents push agent.json -y
docana agents publish <agent-id>

Pushing saves a draft. Publishing makes the changed route available to production executions. Import and export preserve the selection, including webhook nodes in subagents. See the CLI guide for the full file workflow.

Use the API

The route is part of AgentSpec V2 and uses the existing spec endpoints. It is not an execution parameter.

Endpoint	Use
GET /api/v1/agents/schema/	Read the current JSON schema, including the optional config.proxy enum.
POST /api/v1/agents/schema/validate/	Validate { "spec": ... } before saving.
POST /api/v1/agents/	Create an agent with the route in its spec.
PUT /api/v1/agents/{agentId}/spec/	Replace the complete draft spec, retaining its other nodes and settings.
GET /api/v1/agents/{agentId}/export/	Export the selection in an agent bundle.
POST /api/v1/agents/import/	Import a bundle with the selection intact.

Use the API reference for authentication and each endpoint's complete body. The MCP spec tools use the same contract. Existing specs without proxy remain valid.

Test and inspect the request

The node's Test action sends through the selected route on the server. It stops reading a response after 1 MiB to keep the preview bounded, even when the saved node allows a larger attachment. The copied cURL example describes a direct request from the machine where you run it, so it does not prove the regional route worked. To check a published workflow or a larger response, run the agent and inspect the webhook node's execution result.

Regional calls keep the node's timeout, with a relay maximum of 300 seconds. Relay request bodies and JSON responses are limited to 50 MiB. Attachment and text responses keep the webhook's default 30 MiB limit and configurable maximum of 50 MiB. A failed request stays visible as a webhook failure for your workflow to handle.