Webhooks API

Webhooks in Kubiya allow you to receive real-time notifications when specific events occur in your workspace. This API enables you to create, manage, and delete webhook endpoints that receive event notifications.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

List all webhooks

GET

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Create a webhook

POST

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Request Body

List Webhooks

Retrieve all webhooks configured in your workspace.

GET /v1/webhooks

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "webhook-12345",
    "url": "https://example.com/webhook",
    "events": ["execution.completed", "teammate.created"],
    "description": "Notification webhook for executions and teammate creation",
    "created_at": "2023-04-01T12:00:00Z",
    "updated_at": "2023-04-01T12:00:00Z",
    "status": "active"
  }
]

Get Webhook Details

Retrieve details about a specific webhook.

GET /v1/webhooks/{webhook_id}

Path Parameters

Name	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "webhook-12345",
  "url": "https://example.com/webhook",
  "events": ["execution.completed", "teammate.created"],
  "description": "Notification webhook for executions and teammate creation",
  "created_at": "2023-04-01T12:00:00Z",
  "updated_at": "2023-04-01T12:00:00Z",
  "status": "active",
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz",
  "delivery_attempts": 120,
  "successful_deliveries": 118,
  "failed_deliveries": 2,
  "last_triggered_at": "2023-04-10T15:30:00Z"
}

Create Webhook

Create a new webhook endpoint.

POST /v1/webhooks

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "url": "https://example.com/webhook",
  "events": ["execution.completed", "teammate.created"],
  "description": "Notification webhook for executions and teammate creation"
}

Available Event Types

Event	Description
`execution.started`	Triggered when a tool execution starts
`execution.completed`	Triggered when a tool execution completes
`execution.failed`	Triggered when a tool execution fails
`teammate.created`	Triggered when a new teammate is created
`teammate.updated`	Triggered when a teammate is updated
`teammate.deleted`	Triggered when a teammate is deleted
`source.created`	Triggered when a new source is created
`source.updated`	Triggered when a source is updated
`source.synced`	Triggered when a source is synchronized
`tool.created`	Triggered when a new tool is created
`tool.updated`	Triggered when a tool is updated
`tool.deleted`	Triggered when a tool is deleted

Response

{
  "id": "webhook-12345",
  "url": "https://example.com/webhook",
  "events": ["execution.completed", "teammate.created"],
  "description": "Notification webhook for executions and teammate creation",
  "created_at": "2023-04-01T12:00:00Z",
  "updated_at": "2023-04-01T12:00:00Z",
  "status": "active",
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz"
}

Store the secret value returned when creating a webhook securely. This secret is used to validate that incoming webhook requests are from Kubiya. It will only be shown once when the webhook is created.

Update Webhook

Update an existing webhook.

PUT /v1/webhooks/{webhook_id}

Path Parameters

Name	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook to update

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "url": "https://new-example.com/webhook",
  "events": ["execution.completed", "execution.failed"],
  "description": "Updated webhook for execution events only",
  "status": "active"
}

Response

{
  "id": "webhook-12345",
  "url": "https://new-example.com/webhook",
  "events": ["execution.completed", "execution.failed"],
  "description": "Updated webhook for execution events only",
  "created_at": "2023-04-01T12:00:00Z",
  "updated_at": "2023-04-10T14:30:00Z",
  "status": "active"
}

Delete Webhook

Delete a webhook.

DELETE /v1/webhooks/{webhook_id}

Path Parameters

Name	Type	Required	Description
`webhook_id`	string	Yes	ID of the webhook to delete

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

A successful delete operation returns an HTTP 200 status with no response body.

Webhook Events

When a subscribed event occurs, Kubiya sends an HTTP POST request to your webhook URL with details about the event.

Request Headers

Name	Description
`User-Agent`	Kubiya-Webhook/1.0
`Content-Type`	application/json
`X-Kubiya-Event`	Type of event (e.g., `execution.completed`)
`X-Kubiya-Signature`	HMAC signature of the request body using your webhook secret
`X-Kubiya-Timestamp`	Unix timestamp when the event was sent
`X-Kubiya-Request-ID`	Unique ID for the webhook request

Request Body Example (execution.completed)

{
  "event_type": "execution.completed",
  "timestamp": "2023-04-10T15:30:00Z",
  "data": {
    "execution": {
      "id": "exec-67890",
      "tool_id": "tool-12345",
      "tool_name": "create_ec2_instance",
      "teammate_id": "teammate-54321",
      "teammate_name": "AWS Assistant",
      "status": "success",
      "started_at": "2023-04-10T15:29:55Z",
      "completed_at": "2023-04-10T15:30:00Z",
      "duration_ms": 5000,
      "inputs": {
        "instance_type": "t2.micro",
        "region": "us-west-2"
      },
      "outputs": {
        "instance_id": "i-0123456789abcdef",
        "status": "pending"
      }
    }
  }
}

Example Usage

Create a Webhook

curl -X POST "https://api.kubiya.ai/v1/webhooks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["execution.completed", "teammate.created"],
    "description": "Notification webhook for executions and teammate creation"
  }'

Update a Webhook

curl -X PUT "https://api.kubiya.ai/v1/webhooks/webhook-12345" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-example.com/webhook",
    "events": ["execution.completed", "execution.failed"],
    "description": "Updated webhook for execution events only"
  }'

Delete a Webhook

curl -X DELETE "https://api.kubiya.ai/v1/webhooks/webhook-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"

Verifying Webhook Signatures

To verify that a webhook request is genuinely from Kubiya, you should validate the signature provided in the X-Kubiya-Signature header. Here's how to do it:

# Example using bash and OpenSSL
webhook_secret="whsec_abcdefghijklmnopqrstuvwxyz"
payload=$(cat /dev/stdin)  # The request body
signature_header="X-Kubiya-Signature value from request"
 
# Compute the expected signature
expected_signature=$(echo -n "$payload" | openssl dgst -sha256 -hmac "$webhook_secret" | cut -d' ' -f2)
 
# Compare with the provided signature
if [ "$expected_signature" = "$signature_header" ]; then
  echo "Signature verified"
else
  echo "Signature verification failed"
fi

For improved reliability, your webhook endpoint should respond with a 2xx status code quickly (within 5 seconds) to acknowledge receipt of the event. Any processing of the event should be done asynchronously.

Common Errors

HTTP Status	Description
400	Bad Request - Invalid webhook configuration
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to manage webhooks
404	Not Found - The specified webhook was not found
409	Conflict - A webhook with the same URL and events already exists
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up webhooks, you can:

Monitor executions through webhook notifications
React to teammate lifecycle events
Track changes to tools and sources

Webhooks API

List all webhooks

Create a webhook

On this page