Incoming WebHook Trigger

Incoming WebHook: External Event-Driven Automation

The Incoming WebHook Condition enables external systems to trigger Krill automation workflows by sending HTTP requests to dedicated webhook endpoints. This bridges the gap between external applications and your Krill automation, allowing third-party services, custom applications, or other systems to initiate workflows on demand.

Info: This is a Trigger node type that can be used to trigger workflows based on external events. When an HTTP request is received at the configured endpoint, this trigger executes all of its child executor nodes.

Info: This feature uses TargetingNodeMetaData, which means it can optionally be configured to read from data sources and write received webhook data to target nodes like Data Points, Serial Devices, GPIO Pins, or other endpoints.

Overview

Incoming WebHooks act as the entry point for external integration with your Krill automation system. Any system capable of making HTTP requests can trigger Krill workflows—whether it’s a cloud service, another IoT platform, a custom application, or even a simple cURL command.

Key Features

• HTTP Endpoint Creation: Automatically generates unique webhook URLs for each trigger
• Multiple HTTP Methods: Support for GET, POST, PUT, DELETE operations
• Payload Handling: Receive and process JSON or form data payloads
• Target Integration: Write received data to Data Points or other targets
• Real-Time Triggering: Instant workflow execution on request receipt
• Secure Access: Webhook paths are unique to prevent unauthorized access
• Source Data Flow: Pass received data to child executors

Incoming WebHook Processing Flow

graph TD
    A[External System] --> B[HTTP Request to Webhook URL]
    B --> C[Krill Server Receives Request]
    C --> D[Match Webhook Path to Trigger Node]
    D --> E{Valid Request?}
    E -->|Yes| F[Set Node to EXECUTED]
    E -->|No| G[Return Error Response]
    F --> H[Extract Request Payload]
    H --> I[Update Target Data Points]
    I --> J[Execute Child Nodes]
    J --> K[Return Success Response]

How It Works

When an HTTP request hits an Incoming WebHook endpoint:

1. Request Reception: Krill Server receives the HTTP request at the webhook path
2. Trigger Matching: System identifies which webhook trigger matches the request path
3. Validation: Verifies the request method matches the configured method
4. State Transition: Trigger node transitions to EXECUTED state
5. Payload Processing: Extracts data from request body or parameters
6. Target Updates: Writes received data to configured target Data Points
7. Child Execution: Executes all child executor nodes
8. Response: Returns appropriate HTTP response to caller

Configuration

Field	Description	Required
path	Unique webhook path (auto-generated or custom)	Yes
method	HTTP method to respond to (GET, POST, etc.)	Yes
targets	Target Data Point IDs to receive payload data	No
sources	Source node IDs for contextual data	No

Use Cases

• Third-Party Integration: Receive notifications from external services (GitHub, AWS, etc.)
• IoT Gateway: Accept data from devices that can make HTTP requests
• Custom Applications: Trigger workflows from your own applications
• Cloud Services: Connect cloud functions to local automation
• Cross-Platform: Link multiple automation platforms together
• Manual Triggers: Trigger workflows via cURL or browser
• Testing: Easily test automation workflows during development

Example Workflows

Receive GitHub Deployment Webhook:

1. Trigger: Incoming WebHook (POST /webhook/github-deploy)
2. Executor: Lambda (parse deployment data)
3. Executor: OutgoingWebHook (notify Slack)
4. Result: Deployment notifications sent to team

Remote Sensor Data Ingestion:

1. Trigger: Incoming WebHook (POST /webhook/sensor-data)
2. Target: Update temperature Data Point
3. Trigger: High Threshold (if temperature > 80)
4. Executor: OutgoingWebHook (send alert)

Manual Workflow Trigger:

1. Trigger: Incoming WebHook (GET /webhook/start-backup)
2. Executor: Lambda (run backup script)
3. Executor: OutgoingWebHook (send completion email)
4. Result: On-demand backup via URL call

IFTTT/Zapier Integration:

1. Trigger: Incoming WebHook (POST /webhook/ifttt)
2. Executor: Logic Gate (process conditions)
3. Executor: Pin Control (control hardware)
4. Result: Cloud automation controls local hardware

Webhook URL Format

Incoming WebHook endpoints are accessible at:

https://<your-krill-server>:<port>/webhook/<path>

or for local development:

http://localhost:<port>/webhook/<path>

Request Examples

POST with JSON Body:

curl -X POST https://krill.local:8080/webhook/sensor-data \
  -H "Content-Type: application/json" \
  -d '{"temperature": 25.5, "humidity": 60}'

GET with Parameters:

curl "https://krill.local:8080/webhook/trigger?action=start&level=5"

POST with Form Data:

curl -X POST https://krill.local:8080/webhook/form \
  -d "sensor=temp1&value=72.5"

Integration with Data Points

When targets are configured, the webhook can automatically update Data Points:

Webhook receives: {"value": 25.5, "unit": "celsius"}
  └─> Target Data Point: Updated with 25.5
      └─> Trigger: Threshold monitors
          └─> Executor: Automation chain continues

Security Considerations

• Unique Paths: Use long, random paths to prevent guessing
• Network Security: Place behind firewall or reverse proxy
• TLS/SSL: Always use HTTPS in production
• Rate Limiting: Configure rate limits on your server
• Input Validation: Validate incoming data in Lambda scripts
• Authentication: Consider adding API key validation in Lambda

Integration Points

• Data Points: Write received data directly to time-series storage
• Executors: Trigger any executor chain from external events
• Lambda: Custom processing of webhook payloads
• Logic Gates: Conditional automation based on webhook data
• MQTT: Bridge HTTP webhooks to MQTT topics
• OutgoingWebHook: Forward or transform webhook data

Comparison with Other Triggers

Trigger Type	Activation	Use Case
Incoming WebHook	External HTTP request	Integration with external systems
Button	Manual user click	On-demand operations
Cron Timer	Schedule-based	Recurring tasks
Threshold	Value-based	Automatic responses

Best Practices

• Idempotency: Design workflows to handle duplicate webhook calls
• Logging: Log incoming webhook requests for debugging
• Timeouts: Ensure workflows complete quickly to return responses
• Error Handling: Return meaningful error responses
• Testing: Test webhooks thoroughly with tools like Postman
• Documentation: Document webhook endpoints for API consumers
• Monitoring: Track webhook success/failure rates

Common Integrations

Service	Integration Pattern
GitHub	Repository webhooks for CI/CD triggers
AWS SNS	Cloud event notifications
IFTTT	Connect to hundreds of services
Zapier	No-code workflow automation
Home Assistant	Smart home event forwarding
Custom Apps	Direct HTTP integration

Incoming WebHooks are the essential integration point that allows external systems to communicate with and trigger your Krill automation workflows.