kubiya_webhook

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:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
At least one configured agent or workflow to trigger
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

Conditional Workflows

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"
}

Teams Integration

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:

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

Webhook Not Triggering

Workflow Execution Issues

Notification Delivery Problems

Getting Started

Resources

kubiya_webhook

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Conditional Required Arguments

Optional Arguments

Workflow Structure

Attributes Reference

Import

Best Practices

Security

Performance

Reliability

Maintenance

Compatibility

Troubleshooting

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Arguments Reference

​Required Arguments

​Conditional Required Arguments

​Optional Arguments

​Workflow Structure

​Attributes Reference

​Import

​Best Practices

Security

Performance

Reliability

Maintenance

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Conditional Required Arguments

Optional Arguments

Workflow Structure

Attributes Reference

Import

Best Practices

Compatibility

Troubleshooting