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

Method	Path	Description
GET	`/api/v1/webhooks`	List all webhooks
GET	`/api/v1/webhooks/{webhookId}`	Get webhook details
POST	`/api/v1/webhooks`	Create a new webhook
PUT	`/api/v1/webhooks/{webhookId}`	Update a webhook
DELETE	`/api/v1/webhooks/{webhookId}`	Delete a webhook
GET	`/api/v1/webhooks/{webhookId}/deliveries`	Get webhook delivery history

Common Response Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

List Webhooks

Retrieve all webhooks configured in your workspace.

GET /api/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",
    "secret": "whsec_abcdefghijklmnopqrstuvwxyz",
    "delivery_attempts": 120,
    "successful_deliveries": 118,
    "failed_deliveries": 2,
    "last_triggered_at": "2023-04-10T15:30:00Z"
  }
]

Get Webhook Details

Retrieve details about a specific webhook.

GET /api/v1/webhooks/{webhookId}

Path Parameters

Name	Type	Required	Description
`webhookId`	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 /api/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"
}

Required Fields

url: The URL where webhook events will be sent
events: Array of event types to subscribe to

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

Path Parameters

Name	Type	Required	Description
`webhookId`	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",
  "secret": "whsec_abcdefghijklmnopqrstuvwxyz",
  "delivery_attempts": 120,
  "successful_deliveries": 118,
  "failed_deliveries": 2,
  "last_triggered_at": "2023-04-10T15:30:00Z"
}

Delete Webhook

Delete a webhook.

DELETE /api/v1/webhooks/{webhookId}

Path Parameters

Name	Type	Required	Description
`webhookId`	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.

Get Webhook Delivery History

Retrieve the delivery history for a specific webhook.

GET /api/v1/webhooks/{webhookId}/deliveries

Path Parameters

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

Query Parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum number of deliveries to return (default: 50)
`page`	integer	No	Page number for pagination

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "delivery-12345",
    "webhook_id": "webhook-12345",
    "event": "execution.completed",
    "status": "success",
    "response_code": 200,
    "response_body": "OK",
    "created_at": "2023-04-10T15:30:00Z",
    "request_body": {
      "event": "execution.completed",
      "data": {
        "execution_id": "exec-12345",
        "status": "completed"
      }
    }
  }
]

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

Available Events

Event	Description
`execution.completed`	Triggered when an execution completes successfully
`execution.failed`	Triggered when an 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
`knowledge.created`	Triggered when new knowledge is created
`knowledge.updated`	Triggered when knowledge is updated
`knowledge.deleted`	Triggered when knowledge is deleted

Request Body Example (execution.completed)

{
  "event": "execution.completed",
  "data": {
    "execution_id": "exec-12345",
    "status": "completed",
    "started_at": "2023-04-10T15:25:00Z",
    "completed_at": "2023-04-10T15:30:00Z",
    "duration_ms": 300000,
    "result": {
      "success": true,
      "output": "Task completed successfully"
    }
  }
}

The webhook secret is used to verify that requests are coming from Kubiya. You should verify the signature of incoming requests using the HMAC-SHA256 algorithm with your webhook secret.

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 Status	Description
400	Bad Request - Invalid request body or missing required fields
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to perform this action
404	Not Found - The specified webhook was not found
500	Internal 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

Webhooks API

On this page