HTTP-based workflow triggering with custom endpoints, authentication, and real-time payload processing

Webhook Trigger

The Webhook trigger enables HTTP-based workflow execution by exposing custom endpoints that external systems can call. It provides flexible authentication, payload validation, and real-time processing capabilities for seamless integration with third-party services.

Configuration

Input Schema

Field	Type	Required	Description
`endpoint`	`string`	Yes	Custom endpoint path (e.g., "/my-webhook")
`method`	`"GET" \| "POST"`	No	HTTP method to accept (defaults to POST)
`authentication`	`object`	No	Authentication configuration
`validation`	`object`	No	Payload validation rules
`response`	`object`	No	Custom response configuration

Basic Configuration

triggers:
  simple_webhook:
    type: "webhook"
    input:
      endpoint: "/deploy-notification"
      method: "POST"

Authentication Options

# Public webhook (use with caution)
triggers:
  public_webhook:
    type: "webhook"
    input:
      endpoint: "/public-endpoint"
      method: "POST"

Use for internal services or non-sensitive data. Not recommended for production environments with external access.

# Secure with bearer token
triggers:
  secure_webhook:
    type: "webhook"
    input:
      endpoint: "/secure-endpoint"
      method: "POST"
      authentication:
        type: "bearer"
        secret: "{{ secrets.webhook_token }}"

Standard OAuth-style authentication. Simple and secure for most third-party integrations.

# API key in header
triggers:
  api_key_webhook:
    type: "webhook"
    input:
      endpoint: "/api-endpoint"
      authentication:
        type: "api_key"
        header: "X-API-Key"
        secret: "{{ secrets.api_key }}"

Common pattern for API services. Customize the header name to match your service requirements.

# Multiple custom headers
triggers:
  custom_auth_webhook:
    type: "webhook"
    input:
      endpoint: "/custom-auth"
      authentication:
        type: "custom"
        required_headers:
          - "X-Source-System"
          - "X-Request-ID"
        secrets:
          X-Auth-Token: "{{ secrets.auth_token }}"

Maximum flexibility for complex authentication schemes requiring multiple headers or custom validation.

# GitHub-style signature verification
triggers:
  github_webhook:
    type: "webhook"
    input:
      endpoint: "/github-events"
      authentication:
        type: "signature"
        algorithm: "sha256"
        header: "X-Hub-Signature-256"
        secret: "{{ secrets.github_webhook_secret }}"

Highest security level. Verifies payload integrity and authenticity using cryptographic signatures.

Payload Validation

Schema Validation

# Validate incoming payload structure
triggers:
  validated_webhook:
    type: "webhook"
    input:
      endpoint: "/user-data"
      validation:
        schema:
          type: "object"
          required: ["userId", "action", "timestamp"]
          properties:
            userId:
              type: "string"
              pattern: "^user_[0-9]+$"
            action:
              type: "string"
              enum: ["created", "updated", "deleted"]
            timestamp:
              type: "string"
              format: "date-time"

Content Type Validation

# Ensure proper content type
triggers:
  json_webhook:
    type: "webhook"
    input:
      endpoint: "/json-only"
      validation:
        content_type: "application/json"
        max_size: "1MB"

Response Configuration

Custom Response

# Return custom response
triggers:
  custom_response_webhook:
    type: "webhook"
    input:
      endpoint: "/custom-response"
      response:
        status: 200
        headers:
          Content-Type: "application/json"
          X-Processed-By: "Helios"
        body:
          status: "received"
          message: "Webhook processed successfully"
          timestamp: "{{ now() }}"

Conditional Responses

# Different responses based on processing
triggers:
  conditional_webhook:
    type: "webhook"
    input:
      endpoint: "/conditional"
      response:
        success:
          status: 200
          body: { status: "success" }
        error:
          status: 400
          body: { status: "error", message: "Invalid payload" }
        timeout:
          status: 408
          body: { status: "timeout", message: "Processing timeout" }

Use Cases

# GitHub deployment webhook
triggers:
  github_deploy:
    type: "webhook"
    input:
      endpoint: "/github-deploy"
      method: "POST"
      authentication:
        type: "signature"
        algorithm: "sha256"
        header: "X-Hub-Signature-256"
        secret: "{{ secrets.github_secret }}"
      validation:
        schema:
          type: "object"
          required: ["repository", "ref", "deployment"]

Perfect for automating deployments and managing CI/CD pipelines. GitHub, GitLab, and other platforms can trigger workflows based on repository events.

# Stripe payment webhook
triggers:
  stripe_payments:
    type: "webhook"
    input:
      endpoint: "/stripe-events"
      authentication:
        type: "signature"
        algorithm: "sha256"
        header: "Stripe-Signature"
        secret: "{{ secrets.stripe_webhook_secret }}"
      validation:
        content_type: "application/json"
        required_headers: ["Stripe-Signature"]

Handle payment events securely with proper signature validation. Essential for e-commerce workflows, subscription management, and financial reconciliation.

# Support ticket webhook
triggers:
  support_ticket:
    type: "webhook"
    input:
      endpoint: "/support-tickets"
      method: "POST"
      authentication:
        type: "bearer"
        secret: "{{ secrets.support_token }}"
      validation:
        schema:
          type: "object"
          required: ["ticket_id", "customer_id", "priority"]
      response:
        status: 202
        body:
          message: "Ticket received and will be processed"
          eta: "< 5 minutes"

Streamline support operations by automatically routing tickets, escalating based on priority, and integrating with CRM systems.

# IoT sensor data
triggers:
  iot_sensors:
    type: "webhook"
    input:
      endpoint: "/sensor-data"
      method: "POST"
      authentication:
        type: "api_key"
        header: "X-Device-Key"
        secret: "{{ secrets.device_key }}"
      validation:
        schema:
          type: "object"
          required: ["device_id", "timestamp", "readings"]
        max_size: "10KB"

Process real-time sensor data from IoT devices with proper validation and size limits. Ideal for monitoring systems, smart buildings, and industrial automation.

# CMS content updates
triggers:
  cms_updates:
    type: "webhook"
    input:
      endpoint: "/content-updates"
      authentication:
        type: "custom"
        required_headers: ["X-CMS-Source", "X-Content-Type"]
      validation:
        content_type: "application/json"
        schema:
          type: "object"
          required: ["content_id", "action", "content_type"]

Automate content workflows when CMS content is created, updated, or published. Perfect for cache invalidation, search indexing, and content distribution.

Advanced Patterns

# Different endpoints for different environments
triggers:
  prod_webhook:
    type: "webhook"
    input:
      endpoint: "/prod/events"
      authentication:
        type: "bearer"
        secret: "{{ secrets.prod_webhook_token }}"
      
  staging_webhook:
    type: "webhook"
    input:
      endpoint: "/staging/events"
      authentication:
        type: "bearer"
        secret: "{{ secrets.staging_webhook_token }}"

Configure different webhook endpoints for production, staging, and development environments with environment-specific authentication and validation rules.

# Implement rate limiting
triggers:
  rate_limited_webhook:
    type: "webhook"
    input:
      endpoint: "/rate-limited"
      validation:
        rate_limit:
          requests_per_minute: 60
          burst_size: 10
      response:
        rate_limit_exceeded:
          status: 429
          headers:
            Retry-After: "60"
          body:
            error: "Rate limit exceeded"

Protect your webhooks from abuse and ensure system stability by implementing rate limiting with configurable thresholds and proper HTTP responses.

# Combined with filter prompt for intelligent processing
triggers:
  filtered_webhook:
    type: "webhook"
    input:
      endpoint: "/filtered-events"
    filterPrompt: |
      Only process webhook calls that:
      - Have valid authentication
      - Contain event type 'order.completed'
      - Are from verified merchant accounts
      - Have transaction amount > $100

Use AI-powered filtering to intelligently process only relevant webhook events based on complex business logic and conditions that would be difficult to express with traditional validation.

Webhook Context

Access webhook-specific information in your workflows:

Available Context Variables

# Webhook-specific context
- "{{ trigger.method }}"           # HTTP method used
- "{{ trigger.endpoint }}"         # Endpoint that was called
- "{{ trigger.headers }}"          # Request headers
- "{{ trigger.query }}"            # Query parameters
- "{{ trigger.body }}"             # Request body
- "{{ trigger.remoteIp }}"         # Client IP address
- "{{ trigger.userAgent }}"        # Client user agent
- "{{ trigger.contentType }}"      # Request content type
- "{{ trigger.contentLength }}"    # Request size

Processing Webhook Data

# Access webhook data in workflow
- id: process_webhook_data
  type: script
  input:
    script: |
      console.log('Webhook received:', {
        method: trigger.method,
        endpoint: trigger.endpoint,
        remoteIp: trigger.remoteIp,
        userAgent: trigger.userAgent,
        bodySize: trigger.contentLength,
        hasAuth: !!trigger.headers.authorization
      });
      
      return {
        processed: true,
        source: trigger.remoteIp,
        data: trigger.body
      };

Best Practices

Always use authentication: Avoid public webhooks for sensitive operations
Validate all inputs: Check payload structure, size, and content
Use HTTPS only: Ensure encrypted communication
Implement rate limiting: Prevent abuse and DoS attacks
Log security events: Track authentication failures and suspicious activity

# Secure webhook configuration
triggers:
  secure_webhook:
    type: "webhook"
    input:
      endpoint: "/secure"
      authentication:
        type: "signature"
        algorithm: "sha256"
        header: "X-Signature"
        secret: "{{ secrets.webhook_secret }}"
      validation:
        content_type: "application/json"
        max_size: "1MB"
        schema:
          type: "object"
          required: ["timestamp", "data"]
      response:
        status: 200
        body: { received: true }

Optimize payload processing: Handle large payloads efficiently
Use async processing: Don't block webhook responses for long operations
Implement timeouts: Prevent hanging requests
Monitor response times: Track webhook performance metrics

# Performance-optimized webhook
triggers:
  fast_webhook:
    type: "webhook"
    input:
      endpoint: "/fast-processing"
      validation:
        max_size: "5MB"
        timeout: "30s"
      response:
        status: 202  # Accepted for async processing
        body: { queued: true }

Return appropriate status codes: Use proper HTTP status codes
Provide meaningful error messages: Help clients understand failures
Implement retry logic: Handle transient failures gracefully
Log all errors: Maintain detailed error logs for debugging

# Error handling configuration
triggers:
  resilient_webhook:
    type: "webhook"
    input:
      endpoint: "/resilient"
      response:
        validation_error:
          status: 400
          body: { error: "Invalid payload format" }
        auth_error:
          status: 401
          body: { error: "Authentication required" }
        server_error:
          status: 500
          body: { error: "Internal server error" }

# Add monitoring to webhook workflows
- id: monitor_webhook
  type: script
  input:
    script: |
      // Log webhook metrics
      metrics.increment('webhook.received', {
        endpoint: trigger.endpoint,
        method: trigger.method,
        source: trigger.remoteIp
      });
      
      metrics.timing('webhook.processing_time', processingTime);
      
      return { monitored: true };

Track key metrics:

Request volume and frequency
Response times and latency
Authentication success/failure rates
Error rates by type
Payload sizes and processing times

# Debug webhook requests
- id: debug_webhook
  type: script
  input:
    script: |
      console.log('Webhook Debug Info:', {
        trigger: {
          method: trigger.method,
          endpoint: trigger.endpoint,
          headers: trigger.headers,
          query: trigger.query,
          bodyPreview: JSON.stringify(trigger.body).substring(0, 200),
          remoteIp: trigger.remoteIp,
          timestamp: trigger.timestamp
        }
      });

Webhook triggers provide the foundation for real-time, event-driven automation that connects your workflows to the broader ecosystem of web services and applications.

Webhook Trigger

Webhook Trigger

Configuration

Input Schema

Basic Configuration

Authentication Options

Payload Validation

Schema Validation

Content Type Validation

Response Configuration

Custom Response

Conditional Responses

Use Cases

Advanced Patterns

Webhook Context

Available Context Variables

Processing Webhook Data

Best Practices

Troubleshooting

Common Issues

Debugging Tips

On this page

Webhook Trigger

Webhook Not Receiving

Authentication Failures

Payload Validation

Response Issues

On this page