Webhook Management with Kubiya CLI

This guide provides comprehensive instructions for creating, configuring, and using webhooks with the Kubiya CLI.

Understanding Webhooks

Webhooks in Kubiya allow you to integrate with external systems, receive notifications, and trigger automation workflows from third-party services. Webhooks can be used to:

• Trigger automation when code is pushed to GitHub

• Execute tools in response to monitoring alerts

• Process incoming data from external systems

• Connect Kubiya with chat platforms like Slack

Listing Webhooks

To see all available webhooks in your organization:

kubiya webhook list

For more detailed output in JSON format:

kubiya webhook list --output json

Creating Webhooks

Basic Webhook Creation

To create a new webhook:

kubiya webhook create --name "github-push" \
                     --description "Trigger automation when code is pushed to GitHub" \
                     --tool "deploy-app"

Interactive Webhook Creation (Wizard)

For guided webhook creation with an interactive wizard:

kubiya webhook wizard

The wizard will walk you through:

• Setting a name and description

• Choosing a communication method (HTTP, Slack, Teams, etc.)

• Configuring templates and template variables

• Setting up authentication and security

Required Parameters:

• --name: A unique name for your webhook

• --description: A description of the webhook's purpose

Optional Parameters:

• --tool: ID of the tool to execute when webhook is triggered

• --teammate: ID of the teammate to use for the webhook

• --prompt: Custom prompt template for the webhook

• --secret: Secret key for webhook verification

• --tags: Tags for categorizing webhooks

• --method: Communication method (HTTP, Slack, Teams)

• --destination: Communication destination (for Slack/Teams)

• --team-name: Microsoft Teams team name

• --channel-name: Microsoft Teams channel name

Viewing Webhook Details

To get detailed information about a specific webhook:

kubiya webhook describe WEBHOOK_ID

This shows the webhook's configuration, URL, and other metadata.

Getting Webhook URL

To get the URL for a webhook:

kubiya webhook url WEBHOOK_ID

This displays the unique URL that can be used to trigger the webhook.

Triggering Webhooks

Manual Triggering (Testing)

You can manually trigger a webhook from the CLI:

kubiya webhook execute WEBHOOK_ID

With payload data:

kubiya webhook execute WEBHOOK_ID --data '{"message":"Hello from CLI"}'

For formal testing with template variables:

kubiya webhook test --id WEBHOOK_ID --data '{"variable1":"value1", "variable2":"value2"}'

External Triggering

External systems can trigger the webhook by sending an HTTP POST request to the webhook URL:

curl -X POST https://webhooks.kubiya.ai/trigger/WEBHOOK_ID \
     -H "Content-Type: application/json" \
     -d '{"message":"Hello from external system"}'

Updating Webhooks

To modify an existing webhook:

kubiya webhook update WEBHOOK_ID \
                     --description "Updated description" \
                     --tool "new-tool-id"

You can update any of the parameters you used when creating the webhook.

Deleting Webhooks

To remove a webhook:

kubiya webhook delete WEBHOOK_ID

You'll be prompted to confirm the deletion.

Importing and Exporting Webhooks

Exporting Webhooks

Export webhooks for backup or migration:

kubiya webhook export --output webhooks.json

Export a specific webhook:

kubiya webhook export --id WEBHOOK_ID --output webhook.json

Importing Webhooks

Import webhooks from a JSON file:

kubiya webhook import webhooks.json

Webhook Templates

Generate a webhook template:

kubiya webhook export --template --output template.json

This creates a template you can modify and later import.

Webhook Security

Using Webhook Secrets

When creating a webhook, you can specify a secret key:

kubiya webhook create --name "secure-webhook" \
                     --description "Secure webhook example" \
                     --secret "your-secret-key"

When calling the webhook from external systems, use the secret to generate an HMAC signature:

# Example in bash with curl
WEBHOOK_URL="https://webhooks.kubiya.ai/trigger/WEBHOOK_ID"
WEBHOOK_SECRET="your-secret-key"
PAYLOAD='{"message":"Secure payload"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

curl -X POST "$WEBHOOK_URL" \
     -H "Content-Type: application/json" \
     -H "X-Kubiya-Signature: sha256=$SIGNATURE" \
     -d "$PAYLOAD"

IP Whitelisting

You can restrict webhook access to specific IP addresses:

kubiya webhook update WEBHOOK_ID --allowed-ips "192.168.1.1,10.0.0.0/24"

Communication Methods

Kubiya webhooks support multiple communication methods:

HTTP Webhooks

kubiya webhook create --name "http-webhook" \
                     --description "HTTP webhook example" \
                     --method "HTTP"

Slack Webhooks

kubiya webhook create --name "slack-webhook" \
                     --description "Slack webhook example" \
                     --method "Slack" \
                     --destination "#channel-name"

Microsoft Teams Webhooks

kubiya webhook create --name "teams-webhook" \
                     --description "Teams webhook example" \
                     --method "Teams" \
                     --team-name "My Team" \
                     --channel-name "General"

Alternatively:

kubiya webhook create --name "teams-webhook" \
                     --description "Teams webhook example" \
                     --method "Teams" \
                     --destination "My Team/General"

Template Variables and Customization

Webhooks can use template variables in their prompts:

kubiya webhook create --name "custom-template" \
                     --description "Template webhook example" \
                     --prompt "Deploy version {{version}} to {{environment}} environment"

When you create a webhook with template variables, the CLI will show you:

• The detected template variables

• How to test the webhook with these variables

Webhook Logging and Monitoring

Viewing Webhook History

To see the history of webhook executions:

kubiya webhook history WEBHOOK_ID

Debugging Webhooks

If you encounter issues with webhooks:

kubiya webhook debug WEBHOOK_ID

This provides detailed information about recent webhook calls and responses.

End-to-End Example: GitHub to Deployment Pipeline

Here's a complete workflow for creating a CI/CD pipeline using Kubiya webhooks:

Step 1: Create a Deployment Tool

First, create a tool that handles deployments (this would be in your source repository).

# deploy-app.yaml
name: "deploy-app"
description: "Deploy application based on GitHub push"
inputs:
  - name: "repository"
    description: "GitHub repository name"
    type: "string"
    required: true
  - name: "branch"
    description: "Git branch"
    type: "string"
    required: true
  - name: "commit"
    description: "Commit SHA"
    type: "string"
    required: true
script: "../scripts/deploy.py"

Step 2: Create a Webhook for GitHub

kubiya webhook create --name "github-deploy" \
                     --description "Automated deployment when code is pushed" \
                     --tool "deploy-app" \
                     --prompt "Deploy code from {{repository}} branch {{branch}} commit {{commit}}" \
                     --secret "webhook-secret-key"

Step 3: Get the Webhook URL

WEBHOOK_URL=$(kubiya webhook url WEBHOOK_ID --output plain)
echo "Webhook URL: $WEBHOOK_URL"

Step 4: Configure GitHub Repository

In your GitHub repository settings:

1. Go to Settings > Webhooks > Add webhook

2. Set Payload URL to the Kubiya webhook URL

3. Set Content type to application/json

4. Set Secret to the same secret key used in Kubiya

5. Select "Just the push event"

6. Enable the webhook

Step 5: Test the Integration

First, test locally with the test command:

kubiya webhook test --id WEBHOOK_ID --data '{"repository":"my-repo", "branch":"main", "commit":"abc123"}'

Then push a commit to your GitHub repository:

git commit -am "Test webhook integration"
git push origin main

Step 6: View Webhook Execution

Check the webhook execution status:

kubiya webhook history WEBHOOK_ID

Step 7: Set Up Notifications

Create another webhook for deployment notifications:

kubiya webhook create --name "deploy-notify" \
                     --description "Send notification when deployment completes" \
                     --method "Slack" \
                     --destination "#deployments" \
                     --prompt "Deployment of {{app}} version {{version}} to {{environment}} completed with status: {{status}}"

Then, modify your deployment tool to trigger this webhook upon completion.

Step 8: Export Your Webhook Configuration

Once you've set up your webhooks, export them for backup or to replicate in other environments:

kubiya webhook export --output github-webhooks.json

For more information on webhook capabilities and advanced configurations, see the official documentation.