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.
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
List Webhooks
Retrieve all webhooks configured in your workspace.
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Webhook Details
Retrieve details about a specific webhook.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
webhookId | string | Yes | ID of the webhook |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Create Webhook
Create a new webhook endpoint.
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
Required Fields
url
: The URL where webhook events will be sentevents
: Array of event types to subscribe to
Response
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.
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
Response
Delete Webhook
Delete a webhook.
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.
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
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)
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
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