Kubiya LogoKubiya Developer Docs

Webhooks API

API endpoints for managing webhooks in the Kubiya platform

Webhooks API

The Webhooks API allows you to manage webhooks that can be triggered by various events in the Kubiya platform. You can create, update, and delete webhooks, as well as view their delivery history.

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.

Endpoints

MethodPathDescription
GET/api/v1/webhooksList all webhooks
GET/api/v1/webhooks/{webhookId}Get webhook details
POST/api/v1/webhooksCreate a new webhook
PUT/api/v1/webhooks/{webhookId}Update a webhook
DELETE/api/v1/webhooks/{webhookId}Delete a webhook

List Webhooks

Retrieve all webhooks configured in your workspace.

GET /api/v1/webhooks

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "agent_id": "...",
    "communication": {
      "destination": "#kubiya_debug",
      "method": "Slack"
    },
    "created_at": "...",
    "created_by": "...",
    "filter": "...",
    "hide_webhook_headers": false,
    "id": "...",
    "managed_by": "",
    "name": "...",
    "org": "...",
    "prompt": "...",
    "source": "...",
    "task_id": "",
    "updated_at": "...",
    "webhook_url": "..."
  }
]

Get Webhook Details

Retrieve details about a specific webhook.

GET /api/v1/webhooks/{webhookId}

Path Parameters

NameTypeRequiredDescription
webhookIdstringYesID of the webhook

Headers

NameRequiredDescription
AuthorizationYesUserKey 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 /api/v1/webhooks

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Request Body

{
  "name": "github-issues",
  "agent": "aws-assistant",
  "filter": "issues",
  "source": "github",
  "prompt": "Process this new GitHub issue",
  "method": "Slack",
  "destination": "#notifications"
}

Notification Methods

MethodDescription
SlackSend notifications to a Slack channel or user
TeamsSend notifications to a Microsoft Teams channel
HttpSend notifications to an HTTP endpoint

Response

{
  "id": "webhook-12345",
  "name": "github-issues",
  "agent": "aws-assistant",
  "filter": "issues",
  "source": "github",
  "prompt": "Process this new GitHub issue",
  "method": "Slack",
  "destination": "#notifications",
  "created_at": "2023-04-01T12:00:00Z",
  "created_by": "user-123"
}

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 /api/v1/webhooks/{webhookId}

Path Parameters

NameTypeRequiredDescription
webhookIdstringYesID of the webhook to update

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/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 /api/v1/webhooks/{webhookId}

Path Parameters

NameTypeRequiredDescription
webhookIdstringYesID of the webhook to delete

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameDescription
User-AgentKubiya-Webhook/1.0
Content-Typeapplication/json
X-Kubiya-EventType of event (e.g., execution.completed)
X-Kubiya-SignatureHMAC signature of the request body using your webhook secret
X-Kubiya-TimestampUnix timestamp when the event was sent
X-Kubiya-Request-IDUnique 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

# List all webhooks
curl -X GET "https://api.kubiya.ai/api/v1/webhooks" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get webhook details
curl -X GET "https://api.kubiya.ai/api/v1/webhooks/webhook-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new webhook
curl -X POST "https://api.kubiya.ai/api/v1/webhooks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-issues",
    "agent": "aws-assistant",
    "filter": "issues",
    "source": "github",
    "prompt": "Process this new GitHub issue",
    "method": "Slack",
    "destination": "#notifications"
  }'
 
# Update a webhook
curl -X PUT "https://api.kubiya.ai/api/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",
    "status": "active"
  }'
 
# Delete a webhook
curl -X DELETE "https://api.kubiya.ai/api/v1/webhooks/webhook-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"

Webhooks are a powerful way to integrate Kubiya with your existing systems. Make sure to handle webhook events securely and implement proper error handling.

Common Errors

HTTP StatusDescription
400Bad Request - Invalid request body or missing required fields
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have permission to perform this action
404Not Found - The specified webhook was not found
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up webhooks, you can:

  • Monitor webhook delivery status through the Webhooks API
  • Set up Agents to process webhook events
  • Configure Sources to trigger webhook events