Skip to main content
Webhooks allow external systems to trigger Kubiya actions when events occur. Use webhooks to:
  • Start agent tasks from CI/CD pipelines
  • Trigger workflows from monitoring alerts
  • Integrate with ticketing systems
  • Automate responses to external events

​
Access

Webhook configuration may be available through:
  • Settings menu
  • Organization settings (user menu > Organization)
  • Infrastructure > Workflows section
The exact location of webhook settings depends on your organization’s configuration and access level.

​
Managing Webhooks

​
Creating a Webhook

  1. Click + Create Webhook
  2. Configure the webhook:
    • Name - Descriptive identifier
    • Target - Agent or Team to receive events
    • Event Types - Which events trigger the webhook
    • Secret - Optional secret for signature verification
  3. Click Create
  4. Copy the generated webhook URL

​
Webhook Details

Each webhook displays:
FieldDescription
NameWebhook identifier
URLEndpoint to send events to
TargetAgent or Team that handles events
StatusActive or Disabled
CreatedCreation timestamp
Last TriggeredMost recent invocation

​
Testing a Webhook

  1. Click the Test button on any webhook
  2. Review the test payload
  3. Click Send Test
  4. Check the target agent’s task kanban for the test task

​
Webhook URL

The generated URL follows this pattern: 
https://compose.kubiya.ai/api/webhooks/{webhook-id}
Use this URL as the destination in your external systems.

​
Sending Events

​
Basic Request

curl -X POST https://compose.kubiya.ai/api/webhooks/{webhook-id} \
  -H "Content-Type: application/json" \
  -d '{"message": "Deploy to production", "environment": "prod"}'

​
With Authentication

If you configured a secret: 
curl -X POST https://compose.kubiya.ai/api/webhooks/{webhook-id} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret-here" \
  -d '{"message": "Deploy to production"}'

​
Event Payload

The webhook payload is passed to the target agent as context: 
{
  "message": "Your request or instruction",
  "environment": "production",
  "triggered_by": "CI/CD Pipeline",
  "metadata": {
    "commit": "abc123",
    "branch": "main"
  }
}
The message field becomes the primary instruction for the agent.

​
Integration Examples

​
GitHub Actions

- name: Trigger Kubiya Agent
  run: |
    curl -X POST ${{ secrets.KUBIYA_WEBHOOK_URL }} \
      -H "Content-Type: application/json" \
      -d '{
        "message": "Deploy ${{ github.sha }} to staging",
        "commit": "${{ github.sha }}",
        "branch": "${{ github.ref_name }}"
      }'

​
PagerDuty

Configure PagerDuty to send alerts to your webhook URL. The alert details are passed to the agent for automated response.

​
Slack Workflows

Create a Slack workflow that posts to your webhook URL when specific conditions are met.

​
Security

​
Webhook Secrets

Always use a webhook secret in production:
  1. Generate a strong random secret
  2. Configure it in the webhook settings
  3. Include it in the X-Webhook-Secret header
  4. Kubiya validates the secret before processing

​
IP Allowlisting

For additional security, configure your firewall to only allow webhook calls from known sources.

​
Payload Validation

Implement payload validation in your calling system to prevent injection attacks.

​
Monitoring

​
Webhook Logs

View recent webhook invocations:
  • Timestamp
  • Source IP
  • Payload received
  • Processing result
  • Target agent response

​
Failed Invocations

Check failed webhooks for:
  • Invalid payloads
  • Authentication failures
  • Target agent errors
  • Rate limiting

​
Rate Limits

Webhooks have rate limits to prevent abuse:
  • Per webhook: 100 requests per minute
  • Per organization: 1000 requests per minute
Exceeding limits returns HTTP 429.

​
Disabling Webhooks

To temporarily stop a webhook:
  1. Find the webhook in the list
  2. Toggle the Status to Disabled
  3. The URL remains valid but requests are rejected
To permanently remove:
  1. Click Delete
  2. Confirm deletion
Deleting a webhook invalidates its URL permanently. Update any external systems using it before deletion.