docs/docs/en/integration/workflow-http-request/index.md
The HTTP Request node enables NocoBase workflows to proactively send requests to any HTTP service, facilitating data exchange and business integration with external systems.
The HTTP Request node is a core integration component in workflows, allowing you to call third-party APIs, internal service interfaces, or other web services during workflow execution to retrieve data or trigger external operations.
The HTTP Request node is a built-in feature of the Workflow plugin. Ensure the Workflow plugin is enabled.
Request URL: Target API address, supports variables
https://api.example.com/users/{{$context.userId}}
Request Method: Select GET, POST, PUT, DELETE, etc.
Request Headers: Configure HTTP Headers
{
"Content-Type": "application/json",
"Authorization": "Bearer {{$context.apiKey}}"
}
Request Parameters:
After HTTP Request node execution, response data can be used in subsequent nodes:
{{$node.data.status}}: HTTP status code{{$node.data.headers}}: Response headers{{$node.data.data}}: Response body data{{$node.data.error}}: Error message (if request failed)// Configuration
URL: https://api.weather.com/v1/current
Method: GET
Query Parameters:
city: {{$context.city}}
key: your-api-key
// Use Response
Temperature: {{$node.data.data.temperature}}
Weather: {{$node.data.data.condition}}
// Configuration
URL: https://qyapi.weixin.qq.com/cgi-bin/message/send
Method: POST
Headers:
Content-Type: application/json
Body:
{
"touser": "{{$context.userId}}",
"msgtype": "text",
"agentid": 1000001,
"text": {
"content": "Order {{$context.orderId}} has been shipped"
}
}
// Configuration
URL: https://api.payment.com/v1/orders/{{$context.orderId}}/status
Method: GET
Headers:
Authorization: Bearer {{$context.apiKey}}
Content-Type: application/json
// Conditional Logic
If {{$node.data.data.status}} equals "paid"
- Update order status to "Paid"
- Send payment success notification
Else If {{$node.data.data.status}} equals "pending"
- Keep order status as "Awaiting Payment"
Else
- Log payment failure
- Notify administrator to handle exception
// Configuration
URL: https://api.crm.com/v1/customers
Method: POST
Headers:
X-API-Key: {{$context.crmApiKey}}
Content-Type: application/json
Body:
{
"name": "{{$context.customerName}}",
"email": "{{$context.email}}",
"phone": "{{$context.phone}}",
"source": "NocoBase",
"created_at": "{{$context.createdAt}}"
}
Headers:
Authorization: Basic base64(username:password)
Headers:
Authorization: Bearer your-access-token
// In Header
Headers:
X-API-Key: your-api-key
// Or in Query
Query Parameters:
api_key: your-api-key
First obtain access_token, then use:
Headers:
Authorization: Bearer {{$context.accessToken}}
Use Log Nodes: Add log nodes before and after HTTP requests to record request and response data
Check Execution Logs: Workflow execution logs contain detailed request and response information
Testing Tools: Test API first using Postman, cURL, etc.
Error Handling: Add conditional logic to handle different response statuses
If {{$node.data.status}} >= 200 and {{$node.data.status}} < 300
- Handle success logic
Else
- Handle failure logic
- Log error: {{$node.data.error}}
For requests that don't require immediate results, consider using asynchronous workflows.
Set timeouts based on actual API response times to avoid excessive waiting.
For infrequently changing data (configurations, dictionaries), consider caching responses.
If making multiple calls to the same API, consider using batch endpoints (if supported).
Configure reasonable retry strategies, but avoid excessive retries that may cause rate limiting.
// Validate response status
if (![200, 201].includes($node.data.status)) {
throw new Error('API request failed');
}
// Validate data format
if (!$node.data.data || !$node.data.data.id) {
throw new Error('Invalid response data');
}
Respect third-party API rate limits to avoid being blocked.
When logging, sanitize sensitive information (passwords, keys, etc.).
| Feature | HTTP Request Node | Webhook Trigger |
|---|---|---|
| Direction | NocoBase calls external | External calls NocoBase |
| Timing | During workflow execution | When external event occurs |
| Purpose | Fetch data, trigger external operations | Receive external notifications, events |
| Typical Scenarios | Call payment API, query weather | Payment callbacks, message notifications |
These two features complement each other to build a complete system integration solution.