Webhooks & Integrations

Webhooks enable event-driven automation by triggering agents or workflows in response to external events from GitHub, Slack, custom services, and more.

Overview

Kubiya webhooks support two target types:

Agent Webhooks

Trigger existing agents with dynamic prompts based on event data

Workflow Webhooks

Execute workflows directly without creating a dedicated agent

Agent Webhooks

Trigger existing agents with JMESPath-templated prompts.

Create Agent Webhook

GitHub PR
Issue Tracking
Deployment Event
Custom Event

kubiya webhook create \
  --name "GitHub PR Review" \
  --source "github" \
  --target "agent" \
  --agent-id "your-agent-id" \
  --method "Slack" \
  --destination "#code-review" \
  --prompt "New PR: {{.event.pull_request.title}} in {{.event.repository.name}}" \
  --filter "event.action == 'opened' && event.pull_request.draft == false"

How it works:

GitHub sends PR opened event
Webhook filters for non-draft PRs
Constructs prompt with PR details
Triggers agent via Slack

JMESPath Templating

Use JMESPath expressions to extract data from events.

Common GitHub Patterns

# Repository information
--prompt "Event in {{.event.repository.name}} ({{.event.repository.full_name}})"

# Pull Request details
--prompt "PR #{{.event.pull_request.number}}: {{.event.pull_request.title}} by {{.event.pull_request.user.login}}"

# Issue information
--prompt "Issue #{{.event.issue.number}}: {{.event.issue.title}}"

# Commit information
--prompt "Push to {{.event.repository.name}}: {{.event.commits[0].message}} by {{.event.pusher.name}}"

# Release information
--prompt "🚀 Release {{.event.release.tag_name}}: {{.event.release.name}}"

# Branch information
--prompt "Branch {{.event.ref}} was {{.event.action}}"

Complex Expressions

# Conditional formatting
--prompt "{{if .event.pull_request.draft}}[DRAFT]{{end}} PR: {{.event.pull_request.title}}"

# Array access
--prompt "{{.event.commits[0].author.name}} pushed {{length .event.commits}} commits"

# Multiple fields
--prompt "{{.event.sender.login}} {{.event.action}} {{.event.pull_request.title}} ({{.event.pull_request.base.ref}} ← {{.event.pull_request.head.ref}})"

Event Filtering

Use JMESPath to filter which events trigger the webhook.

GitHub Filters

# Only non-draft PRs
--filter "event.action == 'opened' && event.pull_request.draft == false"

# Only main branch pushes
--filter "event.action == 'push' && event.ref == 'refs/heads/main'"

# Only PRs with specific label
--filter "event.action == 'opened' && contains(event.pull_request.labels[*].name, 'deploy')"

# Only issues with critical label
--filter "event.action == 'opened' && contains(event.issue.labels[*].name, 'critical')"

# Only releases (not pre-releases)
--filter "event.action == 'published' && event.release.prerelease == false"

# Specific repository
--filter "event.repository.name == 'production-app'"

# Multiple repositories
--filter "contains(['app1', 'app2', 'app3'], event.repository.name)"

# Specific user actions
--filter "event.sender.login == 'deploy-bot' && event.action == 'closed'"

Custom Filters

# Severity-based
--filter "event.severity == 'high' || event.severity == 'critical'"

# Time-based (business hours)
--filter "event.timestamp >= '09:00' && event.timestamp <= '17:00'"

# Environment-based
--filter "event.environment == 'production'"

# Complex conditions
--filter "(event.type == 'incident' && event.priority > 3) || event.type == 'outage'"

Delivery Methods

Slack
Microsoft Teams
HTTP

kubiya webhook create \
  --name "Slack Notification" \
  --method "Slack" \
  --destination "#channel-name" \
  --prompt "Your message here"

# Private channel or DM
--destination "@username"

# Multiple channels (use separate webhooks)
# Create one webhook per channel

Workflow Webhooks

Execute workflows directly in response to events.

Create Workflow Webhook

From File
From URL
Inline Workflow

kubiya webhook create \
  --name "Auto Deploy" \
  --source "github" \
  --target "workflow" \
  --workflow "file://deploy-workflow.yaml" \
  --method "Slack" \
  --destination "#deployments" \
  --runner "kubiya-hosted" \
  --filter "event.action == 'push' && event.ref == 'refs/heads/main'"

Workflow Variables from Events

Pass event data to workflows as variables:

kubiya webhook create \
  --name "Deploy on Release" \
  --source "github" \
  --target "workflow" \
  --workflow "file://deploy.yaml" \
  --filter "event.action == 'published'" \
  --var "version={{.event.release.tag_name}}" \
  --var "environment=production" \
  --var "repository={{.event.repository.name}}" \
  --runner "prod-runner"

deploy.yaml receives:

variables:
  version: "v1.2.3"          # From GitHub release
  environment: "production"   # Static
  repository: "myapp"         # From GitHub event

Event Sources

GitHub Events

Connect GitHub repositories to trigger webhooks.

# Set up GitHub integration first
kubiya integration create github \
  --name "GitHub Integration" \
  --token "ghp_your_token" \
  --org "your-org"

# Create webhook for repository
kubiya webhook create \
  --name "PR Webhook" \
  --source "github" \
  --repository "your-org/your-repo" \
  --events "pull_request,issues,push" \
  --target "agent" \
  --agent-id "agent-id"

Supported GitHub Events:

pull_request - PR opened, closed, merged
issues - Issue opened, closed, labeled
push - Code pushed to branch
release - Release published
deployment - Deployment created
check_run - CI check completed
workflow_run - GitHub Actions completed
star - Repository starred
fork - Repository forked

Slack Events

Respond to Slack messages and interactions.

# Set up Slack integration
kubiya integration create slack \
  --name "Slack Integration" \
  --token "xoxb-your-token" \
  --workspace "your-workspace"

# Create webhook for Slack events
kubiya webhook create \
  --name "Slack Command Handler" \
  --source "slack" \
  --events "message,app_mention" \
  --target "agent" \
  --agent-id "agent-id" \
  --method "Slack" \
  --destination "#channel"

Custom Events

Send custom events to webhooks via API.

# Create webhook for custom events
kubiya webhook create \
  --name "Custom Event Handler" \
  --source "custom" \
  --target "agent" \
  --agent-id "agent-id" \
  --method "HTTP"

# Get webhook URL
kubiya webhook describe <webhook-id> | grep url

Trigger webhook:

# Via curl
curl -X POST https://webhooks.kubiya.ai/v1/hooks/<webhook-id> \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "type": "deployment",
      "environment": "production",
      "version": "v1.2.3",
      "status": "success"
    }
  }'

# Via Python
import requests

webhook_url = "https://webhooks.kubiya.ai/v1/hooks/<webhook-id>"
event_data = {
    "event": {
        "type": "alert",
        "severity": "high",
        "message": "CPU usage above 90%"
    }
}

response = requests.post(webhook_url, json=event_data)
print(response.status_code)

Scheduled Events

Create scheduled webhooks (cron-like).

# Daily backup at 2 AM
kubiya webhook create \
  --name "Daily Backup" \
  --source "schedule" \
  --schedule "0 2 * * *" \
  --target "workflow" \
  --workflow "file://backup.yaml" \
  --runner "backup-runner"

# Every 15 minutes during business hours
kubiya webhook create \
  --name "Health Check" \
  --source "schedule" \
  --schedule "*/15 9-17 * * 1-5" \
  --target "workflow" \
  --workflow "file://health-check.yaml"

# Weekly report every Monday at 9 AM
kubiya webhook create \
  --name "Weekly Report" \
  --source "schedule" \
  --schedule "0 9 * * 1" \
  --target "agent" \
  --agent-id "reporting-agent" \
  --method "Slack" \
  --destination "#reports" \
  --prompt "Generate weekly report"

Webhook Management

List Webhooks

# List all webhooks
kubiya webhook list

# Detailed view
kubiya webhook list --output wide

# Filter by source
kubiya webhook list --source github

# Filter by target
kubiya webhook list --target agent
kubiya webhook list --target workflow

# Sort by creation date
kubiya webhook list --sort created

View Webhook Details

# Describe webhook
kubiya webhook describe <webhook-id>

# Get webhook URL
kubiya webhook url <webhook-id>

# View webhook events (history)
kubiya webhook events <webhook-id>

# View webhook statistics
kubiya webhook stats <webhook-id>

Update Webhook

# Update prompt
kubiya webhook edit <webhook-id> \
  --prompt "Updated prompt: {{.event.title}}"

# Update filter
kubiya webhook edit <webhook-id> \
  --filter "event.action == 'opened' && event.label == 'bug'"

# Update destination
kubiya webhook edit <webhook-id> \
  --destination "#new-channel"

# Disable webhook
kubiya webhook disable <webhook-id>

# Enable webhook
kubiya webhook enable <webhook-id>

Delete Webhook

# Delete webhook
kubiya webhook delete <webhook-id>

# Force delete
kubiya webhook delete <webhook-id> --force

# Delete all webhooks for an agent
kubiya webhook list --agent <agent-id> | \
  xargs -I {} kubiya webhook delete {}

Test Webhook

# Test with sample event
kubiya webhook test <webhook-id> \
  --data '{"event": {"action": "opened", "title": "Test PR"}}'

# Test with file
kubiya webhook test <webhook-id> \
  --data-file github-pr-event.json

# Dry run (don't actually trigger)
kubiya webhook test <webhook-id> \
  --data-file event.json \
  --dry-run

Real-World Examples

Automated Code Review

kubiya webhook create \
  --name "Auto Code Review" \
  --source "github" \
  --events "pull_request" \
  --target "agent" \
  --agent-id "code-review-agent" \
  --method "Slack" \
  --destination "#code-review" \
  --prompt "Review PR #{{.event.pull_request.number}}: {{.event.pull_request.title}} by {{.event.pull_request.user.login}}" \
  --filter "event.action == 'opened' && event.pull_request.draft == false"

CI/CD Pipeline Trigger

kubiya webhook create \
  --name "Auto Deploy on Tag" \
  --source "github" \
  --events "push" \
  --target "workflow" \
  --workflow "file://deploy.yaml" \
  --runner "prod-runner" \
  --method "Slack" \
  --destination "#deployments" \
  --filter "startswith(event.ref, 'refs/tags/v')" \
  --var "version={{.event.ref | split('/') | [-1]}}" \
  --var "environment=production"

Incident Response

kubiya webhook create \
  --name "Incident Response" \
  --source "custom" \
  --target "agent" \
  --agent-id "incident-agent" \
  --method "Slack" \
  --destination "#incidents" \
  --prompt "🚨 Incident: {{.event.title}} - Severity: {{.event.severity}}" \
  --filter "event.severity == 'critical' || event.severity == 'high'"

Scheduled Maintenance

kubiya webhook create \
  --name "Database Backup" \
  --source "schedule" \
  --schedule "0 2 * * *" \
  --target "workflow" \
  --workflow "file://backup.yaml" \
  --runner "backup-runner" \
  --method "Slack" \
  --destination "#ops" \
  --var "database=production" \
  --var "retention_days=30"

Security & Best Practices

Webhook Security

Always validate webhook signatures and use HTTPS endpoints.

# Use webhook secrets for validation
kubiya webhook create \
  --name "Secure Webhook" \
  --source "github" \
  --secret "your-webhook-secret" \
  --target "agent" \
  --agent-id "agent-id"

# Restrict by IP (if supported)
--allowed-ips "192.168.1.0/24,10.0.0.0/8"

# Use HTTPS for all HTTP destinations
--destination "https://secure-endpoint.com/webhook"

Filter Best Practices

✅ Be specific: Filter events to reduce noise
✅ Test filters: Use webhook test before deployment
✅ Log events: Monitor webhook execution
❌ Avoid catch-all: Don’t trigger on every event
❌ Don’t over-filter: Balance specificity with utility

Error Handling

# Configure retry behavior
kubiya webhook create \
  --name "Resilient Webhook" \
  --retry-count 3 \
  --retry-delay "5s" \
  --timeout "30s" \
  --target "workflow" \
  --workflow "file://task.yaml"

# Dead letter queue for failed events
--dlq-enabled \
--dlq-destination "#failed-webhooks"

Monitoring & Debugging

View Webhook Logs

# View recent executions
kubiya webhook logs <webhook-id>

# Follow in real-time
kubiya webhook logs <webhook-id> --follow

# Filter by status
kubiya webhook logs <webhook-id> --status failed
kubiya webhook logs <webhook-id> --status success

# Date range
kubiya webhook logs <webhook-id> \
  --since "2024-01-01" \
  --until "2024-01-31"

Webhook Metrics

# View statistics
kubiya webhook stats <webhook-id>

# Example output:
# Total Executions: 1,234
# Successful: 1,180 (95.6%)
# Failed: 54 (4.4%)
# Avg Response Time: 850ms
# Last Execution: 2 minutes ago

Debugging Failed Webhooks

# Get last failure details
kubiya webhook logs <webhook-id> \
  --status failed \
  --limit 1 \
  --verbose

# Test webhook with sample data
kubiya webhook test <webhook-id> \
  --data-file failed-event.json \
  --debug

# Check filter expression
kubiya webhook describe <webhook-id> | grep filter

# Validate JMESPath expressions
echo '{"event": {"action": "opened"}}' | \
  jq '.event.action == "opened"'

Command Reference

# Create webhook
kubiya webhook create [options]

# List webhooks
kubiya webhook list [--source <source>] [--target <type>]

# View details
kubiya webhook describe <id>
kubiya webhook url <id>
kubiya webhook events <id>
kubiya webhook stats <id>

# Update webhook
kubiya webhook edit <id> [options]
kubiya webhook enable <id>
kubiya webhook disable <id>

# Delete webhook
kubiya webhook delete <id>

# Test webhook
kubiya webhook test <id> [--data <json>] [--data-file <file>]

# View logs
kubiya webhook logs <id> [--follow] [--status <status>]

Next Steps

Workflow Execution

Learn to create workflows for webhooks

Resource Management

Create and manage agents

Integrations

Set up GitHub, Slack, and other integrations

API Reference

Programmatic webhook management

Getting Started

Core Operations

Advanced

​Overview

Agent Webhooks

Workflow Webhooks

​Agent Webhooks

​Create Agent Webhook

​JMESPath Templating

​Common GitHub Patterns

​Complex Expressions

​Event Filtering

​GitHub Filters

​Custom Filters

​Delivery Methods

​Workflow Webhooks

​Create Workflow Webhook

​Workflow Variables from Events

​Event Sources

​GitHub Events

​Slack Events

​Custom Events

​Scheduled Events

​Webhook Management

​List Webhooks

​View Webhook Details

​Update Webhook

​Delete Webhook

​Test Webhook

​Real-World Examples

​Automated Code Review

​CI/CD Pipeline Trigger

​Incident Response

​Scheduled Maintenance

​Security & Best Practices

​Webhook Security

​Filter Best Practices

​Error Handling

​Monitoring & Debugging

​View Webhook Logs

​Webhook Metrics

​Debugging Failed Webhooks

​Command Reference

​Next Steps

Workflow Execution

Resource Management

Integrations

API Reference

Overview

Agent Webhooks

Create Agent Webhook

JMESPath Templating

Common GitHub Patterns

Complex Expressions

Event Filtering

GitHub Filters

Custom Filters

Delivery Methods

Workflow Webhooks

Create Workflow Webhook

Workflow Variables from Events

Event Sources

GitHub Events

Slack Events

Custom Events

Scheduled Events

Webhook Management

List Webhooks

View Webhook Details

Update Webhook

Delete Webhook

Test Webhook

Real-World Examples

Automated Code Review

CI/CD Pipeline Trigger

Incident Response

Scheduled Maintenance

Security & Best Practices

Webhook Security

Filter Best Practices

Error Handling

Monitoring & Debugging

View Webhook Logs

Webhook Metrics

Debugging Failed Webhooks

Command Reference

Next Steps