Webhook Trigger (HTTP-Webhook Listener)

The Webhook Trigger enables workflows to be started by HTTP requests from external systems.

What does this integration do?

The Webhook Trigger creates an HTTP endpoint that waits for incoming POST requests from external systems. When an authenticated request is received, it automatically starts the linked workflow with the transmitted data.

Typical Use Cases:

API Integration: Receive data from external systems and APIs
Event-based Automation: React to events in third-party systems
Real-time Processing: Immediate processing of incoming data
System Notifications: Process alerts and notifications
Workflow Orchestration: Chain processes between different systems

User Configuration

Basic Configuration

Shared Key

Purpose: Security key for authenticating incoming webhook calls
Type: Encrypted storage
Usage: Must be sent with every webhook call
Example: webhook-secret-key-2024
Security: Should be complex and unique

Header Memory (Variable for HTTP Headers)

Purpose: Name of the variable that stores all HTTP headers of the incoming request
Content: JSON object with all request headers
Example Variable: requestHeaders

Example Content:

{
  "content-type": "application/json",
  "user-agent": "MyApp/1.0",
  "authorization": "Bearer token123"
}

Body Memory (Variable for HTTP Body)

Purpose: Name of the variable that stores the content of the incoming request
Content: The entire request body (JSON, text, etc.)
Example Variable: requestBody

Example Content:

{
  "event": "user_created",
  "user_id": "12345",
  "email": "user@example.com"
}

Webhook URL

After configuration, you receive a unique webhook URL:

https://your-vectense-domain.com/api/webhook/workspace-id/workflow-id?key=shared-key

Use this URL in external systems for webhook calls.

External System Configuration

HTTP Request Format

Request Method: POST

Headers:

Content-Type: application/json

URL Parameters:

key: The configured Shared Key for authentication

Request Body:

{
  "event": "payment_completed",
  "order_id": "ORD-12345",
  "amount": 99.99,
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  }
}

Example Calls

cURL Example:

curl -X POST \
  "https://your-domain.com/api/webhook/workspace/workflow?key=your-shared-key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order_created",
    "order_id": "12345",
    "total": 150.00
  }'

JavaScript Example:

fetch(
  "https://your-domain.com/api/webhook/workspace/workflow?key=your-shared-key",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      event: "user_signup",
      user_id: "67890",
      email: "new-user@example.com",
    }),
  }
);

Python Example:

import requests

url = "https://your-domain.com/api/webhook/workspace/workflow"
headers = {"Content-Type": "application/json"}
params = {"key": "your-shared-key"}
data = {
    "event": "payment_failed",
    "order_id": "12345",
    "reason": "insufficient_funds"
}

response = requests.post(url, json=data, headers=headers, params=params)

Workflow Integration

Data Provision

The Webhook Trigger provides the following data for the workflow:

HTTP Headers (if configured):

{
  "content-type": "application/json",
  "user-agent": "GitHub-Hookshot/abc123",
  "x-github-event": "push",
  "x-github-delivery": "12345-67890"
}

Request Body (if configured):

{
  "action": "opened",
  "number": 123,
  "pull_request": {
    "title": "Fix critical bug",
    "user": {
      "login": "developer"
    }
  }
}

Usage in Subsequent Steps

Example access to webhook data:

In LLM Action:

Prompt: "Process the following order: {{requestBody}}"

In HTTP Action:

URL: https://api.example.com/orders
Method: POST
Body: {{requestBody}}

In Script Action:

const orderData = memory.load("requestBody");
const customerEmail = orderData.customer.email;

Practical Examples

GitHub Webhook Integration

External Configuration (GitHub):

Payload URL: https://your-domain.com/api/webhook/workspace/github-workflow?key=github-secret
Content type: application/json
Events: Push, Pull Request

Vectense Configuration:

Shared Key: github-secret-key-2024
Header Memory: githubHeaders
Body Memory: githubPayload

Workflow Usage: Automatic code review, deployment triggers, issue creation

E-Commerce Order Processing

External Configuration (Shop System):

// On order completion
webhook_data = {
  event: "order_completed",
  order_id: order.id,
  customer_email: order.customer.email,
  total_amount: order.total,
  items: order.items,
};

Vectense Configuration:

Shared Key: shop-integration-key
Header Memory: orderHeaders
Body Memory: orderData

Workflow Usage: Send order confirmation, initialize shipping, update accounting

Monitoring Alert Integration

External Configuration (Monitoring System):

{
  "alert": "high_cpu_usage",
  "severity": "warning",
  "server": "web-01",
  "cpu_usage": 85.2,
  "timestamp": "2024-03-15T10:30:00Z"
}

Vectense Configuration:

Shared Key: monitoring-alert-key
Header Memory: alertHeaders
Body Memory: alertData

Workflow Usage: Automatic incident response, team notification, escalation

CRM Contact Update

External Configuration (CRM System):

{
  "event": "contact_updated",
  "contact_id": "12345",
  "changes": {
    "email": "new-email@example.com",
    "status": "qualified_lead"
  },
  "updated_by": "sales_user"
}

Vectense Configuration:

Shared Key: crm-sync-key
Header Memory: crmHeaders
Body Memory: contactUpdate

Workflow Usage: Data synchronization, lead scoring updates, follow-up actions

Technical Details

Schema Configuration

configSchema: {
  sharedKey: {
    name: 'Shared Key',
    reference: 'secured',
    schema: z.string(),
  },
  headerMemory: {
    name: 'Header Memory',
    reference: 'memory-out',
    schema: z.string(),
  },
  bodyMemory: {
    name: 'Body Memory',
    reference: 'memory-out',
    schema: z.string(),
  },
}

Internal Implementation

Webhook Endpoint:

Automatic URL generation based on workspace and workflow
Authentication via URL parameter (Shared Key)
Support for various content types
Automatic JSON parsing for JSON requests

Data Processing:

Header extraction and storage in configured variable
Body parsing and storage in configured variable
Automatic data type detection (JSON, text, etc.)
Error handling for invalid data

Security:

Shared Key validation on every request
Secure storage of Shared Key (encrypted)
Request size limitations
Rate limiting to protect against abuse

Response Behavior

Successful Requests:

HTTP Status: 200 OK
Response Body: {"status": "accepted", "workflow_started": true}

Authentication Errors:

HTTP Status: 401 Unauthorized
Response Body: {"error": "Invalid shared key"}

Invalid Data:

HTTP Status: 400 Bad Request
Response Body: {"error": "Invalid request format"}

System Errors:

HTTP Status: 500 Internal Server Error
Response Body: {"error": "Internal server error"}

Best Practices

Security

Shared Key Management:

Use strong, unique shared keys
Rotate keys regularly
Share keys only with authorized systems
Monitor webhook calls for suspicious activity

Data Validation:

Validate incoming data in subsequent workflow steps
Implement plausibility checks
Sanitize data before further processing

Performance

Request Processing:

Keep webhook workflows lean and fast
Use asynchronous processing for time-consuming operations
Implement idempotency for repeated webhook calls

Monitoring:

Monitor webhook response times
Track success and error rates
Set alerts for unusual webhook activity

Integration

Error Handling:

Implement retry logic in external systems
Define timeout values for webhook calls
Plan for temporary system outages

Documentation:

Document webhook URLs and authentication
Create examples for external developers
Define expected data formats clearly

Maintenance

Versioning:

Plan for changes in webhook formats
Implement backward compatibility where possible
Communicate changes to external systems

Testing:

Test webhooks with realistic data
Use test endpoints for development
Validate webhook behavior under load

The Webhook Trigger enables seamless integration with external systems and provides the foundation for event-driven, real-time automation in Vectense Platform.

What does this integration do?​

User Configuration​

Basic Configuration​

Webhook URL​

External System Configuration​

HTTP Request Format​

Example Calls​

Workflow Integration​

Data Provision​

Usage in Subsequent Steps​

Practical Examples​

GitHub Webhook Integration​

E-Commerce Order Processing​

Monitoring Alert Integration​

CRM Contact Update​

Technical Details​

Schema Configuration​

Internal Implementation​

Response Behavior​

Best Practices​

Security​

Performance​

Integration​

Maintenance​

What does this integration do?

User Configuration

Basic Configuration

Webhook URL

External System Configuration

HTTP Request Format

Example Calls

Workflow Integration

Data Provision

Usage in Subsequent Steps

Practical Examples

GitHub Webhook Integration

E-Commerce Order Processing

Monitoring Alert Integration

CRM Contact Update

Technical Details

Schema Configuration

Internal Implementation

Response Behavior

Best Practices

Security

Performance

Integration

Maintenance