The kubiya_webhook resource allows you to create and manage webhooks in the Kubiya platform. Webhooks enable external systems to trigger Kubiya agents or workflows via HTTP requests, facilitating event-driven automation and real-time integrations.
Webhooks are essential for building responsive automation systems that react to external events like code pushes, deployment notifications, alerts, and data changes.

​
Prerequisites

Before using this resource, ensure you have:
  1. A Kubiya account with API access
  2. An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
  3. At least one configured agent or workflow to trigger
  4. Appropriate integrations configured for notification methods (Slack, Teams)

​
Quick Start

resource "kubiya_agent" "support_agent" {
  name         = "support-assistant"
  runner       = "kubiya-hosted"
  description  = "Customer support agent"
  instructions = "You are a support assistant that helps resolve customer issues."
}

resource "kubiya_webhook" "support_webhook" {
  name   = "customer-support-webhook"
  agent  = kubiya_agent.support_agent.name
  source = "zendesk"
  prompt = "New support ticket received. Please analyze and provide initial response."
}

​
Configuration Examples

Create a webhook for automated incident response:
resource "kubiya_agent" "incident_agent" {
  name         = "incident-responder"
  runner       = "kubiya-hosted"
  description  = "Automated incident response agent"
  instructions = <<-EOT
    You are an incident response agent. When triggered:
    1. Analyze the incident severity
    2. Gather relevant logs and metrics
    3. Create a JIRA ticket
    4. Notify the on-call team
    5. Start initial remediation steps
  EOT
  
  integrations = ["pagerduty", "jira_cloud", "datadog", "slack_integration"]
}

resource "kubiya_webhook" "incident_webhook" {
  name        = "critical-incident-webhook"
  agent       = kubiya_agent.incident_agent.name
  source      = "datadog"
  filter      = "severity:critical"
  prompt      = "Critical incident detected. Initiate incident response protocol."
  
  method      = "Slack"
  destination = "#incidents-critical"
}

​
Advanced Configurations

Create webhooks with conditional logic based on runtime conditions:
resource "kubiya_webhook" "conditional_webhook" {
  name   = "smart-deployment"
  source = "github"
  filter = "release"
  prompt = "New release created, execute smart deployment"
  
  workflow = jsonencode({
    name        = "conditional-deployment"
    description = "Deployment with environment-based conditions"
    steps = [
      {
        name        = "check-environment"
        description = "Determine target environment based on tag"
        executor = {
          type = "tool"
          config = {
            tool_def = {
              name        = "env-checker"
              description = "Check deployment environment"
              type        = "docker"
              image       = "alpine:latest"
              content     = <<-BASH
                if [[ "${RELEASE_TAG}" == *"-prod"* ]]; then
                  echo "production"
                elif [[ "${RELEASE_TAG}" == *"-staging"* ]]; then
                  echo "staging"
                else
                  echo "development"
                fi
              BASH
              args = [
                {
                  name        = "RELEASE_TAG"
                  type        = "string"
                  description = "Release tag name"
                  required    = true
                }
              ]
            }
            args = {
              RELEASE_TAG = "${GITHUB_RELEASE_TAG}"
            }
          }
        }
        output = "TARGET_ENV"
      },
      {
        name        = "deploy-to-environment"
        description = "Deploy to determined environment"
        depends     = ["check-environment"]
        executor = {
          type = "agent"
          config = {
            teammate_name = "deployment-agent"
            message       = "Deploy release ${GITHUB_RELEASE_TAG} to ${TARGET_ENV} environment"
          }
        }
      },
      {
        name        = "run-environment-tests"
        description = "Run environment-specific tests"
        depends     = ["deploy-to-environment"]
        executor = {
          type = "command"
          config = {
            command = "npm run test:${TARGET_ENV}"
          }
        }
      }
    ]
  })
  
  runner      = "kubiya-hosted"
  method      = "Slack"
  destination = "#releases"
}
Configure webhook with Microsoft Teams notifications:
resource "kubiya_webhook" "deployment_webhook" {
  name        = "deployment-notification"
  agent       = "deployment-agent"
  source      = "github-actions"
  filter      = "workflow:deploy"
  prompt      = "Deployment completed. Verify deployment health and report status."
  
  method      = "Teams"
  team_name   = "DevOps Team"
  destination = "Deployments"  # Channel name in Teams
}

​
Arguments Reference

​
Required Arguments

​
name
string
required
The name of the webhook. Must be unique within your organization.

​
Conditional Required Arguments

Either agent or workflow must be specified:
​
agent
string
The name of the agent to trigger with this webhook. Required if no workflow is specified.
​
workflow
string
JSON-encoded workflow definition to execute when webhook is triggered. Required if no agent is specified.

​
Optional Arguments

​
source
string
Source identification for the webhook (e.g., “github”, “datadog”, “custom”). Helps with organizing and filtering webhooks.
​
filter
string
Filter expression for events that will trigger the webhook. Use to restrict webhook triggers to specific conditions.
​
prompt
string
Prompt to send to the agent or workflow when triggered. Provides context for the execution.
​
runner
string
The runner to use for workflow execution. Required when using workflow parameter.
​
method
string
default:"Slack"
Notification method for webhook results. Available options:
  • Slack - Send notifications to Slack channels or users
  • Teams - Send notifications to Microsoft Teams
  • Http - Send HTTP notifications
​
destination
string
Destination for notifications (varies by method):
  • Slack: Channel name with ”#” prefix (e.g., “#alerts”) or username with ”@” prefix
  • Teams: Channel name within the team specified by team_name
  • Http: Not required
​
team_name
string
Team name for Microsoft Teams notifications. Required when method is “Teams”.

​
Workflow Structure

When using the workflow parameter, the JSON structure should include:
​
workflow.name
string
required
Name of the workflow for identification.
​
workflow.description
string
required
Description of the workflow’s purpose.
​
workflow.steps
array
required
Array of workflow steps, each containing:
​
workflow.steps[].name
string
required
Unique name for the step.
​
workflow.steps[].description
string
required
Description of what the step does.
​
workflow.steps[].executor
object
required
Executor configuration with type and config properties.
​
workflow.steps[].depends
array
Array of step names this step depends on for execution order.
​
workflow.steps[].output
string
Variable name to store step output for use in subsequent steps.

​
Attributes Reference

In addition to all arguments above, the following attributes are exported:
​
id
string
The unique identifier of the webhook.
​
url
string
The URL to trigger the webhook (sensitive).
​
created_at
string
The timestamp when the webhook was created.
​
created_by
string
The user who created the webhook.
​
status
string
The current status of the webhook.
​
workflow_id
string
The ID of the associated workflow (when using workflow parameter).

​
Import

Webhooks can be imported using their ID: 
terraform import kubiya_webhook.example <webhook-id>

​
Best Practices

Security

  • Use filters to restrict webhook triggers to specific events
  • Implement proper authentication and authorization for webhook endpoints
  • Validate webhook payloads to prevent malicious triggers
  • Monitor webhook execution for suspicious activity

Performance

  • Design workflows to be efficient and avoid long-running operations
  • Use appropriate timeouts and retry mechanisms
  • Consider rate limiting for high-frequency webhooks
  • Implement proper error handling and recovery

Reliability

  • Include error handling steps in workflows
  • Set up monitoring and alerting for webhook failures
  • Test webhooks with sample payloads before production use
  • Implement idempotent operations where possible

Maintenance

  • Use descriptive names that indicate the webhook’s purpose and source
  • Document expected payload formats and trigger conditions
  • Version control your webhook configurations
  • Regularly review and update webhook configurations

​
Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • Workflow support requires appropriate runner configuration
  • Notification methods require corresponding integrations to be configured
Important Considerations:
  • Some features may require specific Kubiya platform tier
  • Be aware of rate limits when designing high-frequency webhooks
  • Ensure proper network access for webhook URL endpoints
  • Test webhook integrations thoroughly before production deployment

​
Troubleshooting

  • Verify the webhook URL is accessible from the source system
  • Check filter expressions for syntax and logic errors
  • Ensure the source system is sending requests in the expected format
  • Review webhook logs for error messages
  • Verify the runner is active and has proper permissions
  • Check that all required dependencies are available in the execution environment
  • Review workflow step dependencies for circular references
  • Ensure proper variable passing between workflow steps
  • Verify integration configurations for Slack/Teams
  • Check channel names and team configurations
  • Ensure proper permissions for notification delivery
  • Test notification methods independently