Skip to main content

Web Service Action

The Web Service Action sends requests to external web services and stores the responses for further processing.

What does this integration do?​

The Web Service Action enables communicating with external web services and online systems. It can send different types of requests, transmit data, and store responses in variables for subsequent workflow steps.

Typical Use Cases:

  • Service Integration: Retrieve or send data to external services
  • Data Queries: Load information from web services
  • Notifications: Notify external systems about events
  • Data Transfer: Upload or update data in external systems
  • Status Queries: Check system status or data availability
  • Authentication: Login or access token management with external services

User Configuration​

Request Configuration​

URL (Target Address)

  • Purpose: Complete web address of the service you want to connect to
  • Format: Complete web address (starting with https:// or http://)
  • Supports: Variable insertion with {{variableName}}
  • Examples:
    • https://api.example.com/users
    • https://service.company.com/orders/{{orderId}}
    • http://internal.system/webhook

Request Method

  • Purpose: Type of request to send
  • Options:
    • GET - Retrieve information
    • POST - Create new information
    • PUT - Completely update information
    • PATCH - Partially update information
    • DELETE - Delete information

Content/Body (Request Body) - Optional

  • Purpose: Data sent in the request body
  • Format: Variable name or JSON structure
  • Data Sources:
    • Variable from previous workflow steps
    • Direct JSON input
    • Empty for GET requests
  • Examples:
    • orderData (variable name)
    • {"name": "{{customerName}}", "email": "{{email}}"}

Output Configuration​

Result (Body) - Variable for Response

  • Purpose: Name of the variable that stores the HTTP response
  • Content: Response body of the HTTP request
  • Format: JSON, text, or binary data depending on API response
  • Example Variable: apiResponse

How it Works​

Request Processing​

URL Parsing:

  • Validation of URL syntax
  • Variable interpolation in URLs
  • Automatic protocol detection

Body Processing:

  • Automatic content-type detection
  • JSON serialization for objects
  • Variable substitution from workflow memory

Header Management:

  • Automatic setting of Content-Type
  • JSON format: application/json
  • Text format: text/plain

Response Handling​

Status Code Handling:

  • Successful requests (2xx) are processed
  • Error status codes (4xx, 5xx) throw exceptions
  • Automatic response body extraction

Data Type Detection:

  • Automatic JSON parsing for JSON responses
  • Text handling for other content types
  • Preservation of original data structure

Workflow Integration​

Request Data​

Simple GET Request:

URL: https://api.weather.com/v1/current?city=Berlin
Method: GET
Content/Body: [empty]

POST with JSON Data:

URL: https://api.crm.com/contacts
Method: POST
Content/Body: contactData (variable)

Where contactData contains:
{
  "name": "John Doe",
  "email": "john@example.com",
  "company": "Example Inc"
}

Response Data​

API Response (Result Variable):

{
  "id": 12345,
  "status": "success",
  "data": {
    "userId": 67890,
    "name": "John Doe",
    "created": "2024-03-15T10:30:00Z"
  },
  "message": "User created successfully"
}

Usage in Subsequent Steps​

Using Response Data:

Variable: apiResponse

In LLM Action:
"Analyze the following API response: {{apiResponse}}"

In Script Action:
const response = memory.load('apiResponse');
const userId = response.data.userId;
const success = response.status === 'success';

Practical Examples​

CRM System Integration​

Configuration:

  • URL: https://crm.company.com/api/v1/leads
  • HTTP-Method: POST
  • Content/Body: leadData
  • Result: crmResponse

Usage: Transfer new leads to CRM, validate response status

Weather Data Retrieval​

Configuration:

  • URL: https://api.openweathermap.org/data/2.5/weather?q={{city}}&appid={{apiKey}}
  • HTTP-Method: GET
  • Result: weatherData

Usage: Weather data for reports, decision logic based on weather

E-Commerce API Integration​

Configuration:

  • URL: https://shop.company.com/api/orders/{{orderId}}/status
  • HTTP-Method: PUT
  • Content/Body: statusUpdate
  • Result: updateResponse

Usage: Update order status, synchronize inventory management

Webhook Notification​

Configuration:

  • URL: https://hooks.slack.com/services/{{slackHook}}
  • HTTP-Method: POST
  • Content/Body: slackMessage
  • Result: webhookResponse

Usage: Team notifications, alert forwarding

Database API Integration​

Configuration:

  • URL: https://db-api.company.com/records
  • HTTP-Method: GET
  • Result: databaseRecords

Usage: Data retrieval for reports, data validation

Technical Details​

Schema Configuration​

configSchema: {
  url: {
    name: 'URL',
    description: 'Address to access',
    schema: z.string().url(),
  },
  method: {
    name: 'HTTP-Method',
    schema: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']),
  },
  body: {
    name: 'Content/Body',
    parser: true,
    reference: 'memory-in',
    schema: z.record(z.string(), z.any()).optional(),
  },
  out_results: {
    name: 'Result (Body)',
    reference: 'memory-out',
    schema: z.string(),
  },
}

Internal Implementation​

HTTP Client:

  • Uses Axios for robust HTTP communication
  • Automatic request/response interceptors
  • Configurable timeouts and retry logic

Memory Integration:

  • Loads request body from workflow memory
  • Stores response automatically in configured variable
  • Supports complex data structures

Error Handling:

  • Detailed logging of request/response
  • HTTP status code-based error handling
  • Graceful degradation for network errors

Best Practices​

API Integration​

URL Management:

  • Use base URLs as variables for flexibility
  • Implement API versioning in URLs
  • Validate URL parameters before requests

Authentication:

  • Use secure headers for API keys
  • Implement token refresh mechanisms
  • Monitor authentication errors

Request Optimization​

Body Data:

  • Validate request body structure
  • Use schema validation for API compatibility
  • Limit body sizes for performance

HTTP Methods:

  • Use semantically correct HTTP verbs
  • Implement idempotency for PUT/PATCH
  • Consider caching behavior

Performance​

Response Handling:

  • Implement timeouts for slow APIs
  • Use streaming for large responses
  • Cache responses where appropriate

Error Handling:

  • Implement retry logic for temporary errors
  • Distinguish between different error types
  • Log API metrics for monitoring

Security​

Data Transmission:

  • Use HTTPS for all production APIs
  • Validate SSL certificates
  • Implement request signing where required

Data Validation:

  • Validate API responses before further processing
  • Sanitize input data
  • Implement rate limiting

The HTTP Action is a versatile tool for integrating external APIs and web services into Vectense Platform workflows and enables seamless data exchange between systems.