# Kiteworks API — webhook Operations

**6 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/webhook.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/webhook.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## GET /webhooks

**Summary:** Get all webhooks

Retrieves a list of all webhooks with optional pagination

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `offset` | query | no | Offset value (must be 0 or a positive integer) |
| `limit` | query | no | Limit count (must be 0 or a positive integer) |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Webhooks retrieved successfully |
| 400 | Invalid pagination parameters |
| 500 | Internal server error |

**Response Examples:**

**400:**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid parameter, details:[0-limit must be integer]"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not get webhooks"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/webhooks"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## POST /webhooks

**Summary:** Create a new webhook

Creates a new webhook based on the body content
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `url` | string | yes | URL contains the webhook URL |
| `token` | string | no | Token contains the webhook Token (optional; if provided must not be empty or whitespace-only) |
| `secret` | string | yes | Secret contains the webhook Secret |
| `enabled` | boolean | no | Enabled is the value of the webhook enable/disable (default is true when omitted) |
| `subscriptions` | string[] | yes | Subscriptions is a list of NATS subject filter patterns associated with the webhook. Each entry must be non-empty and contain only letters, numbers, dot, asterisk, underscore, hyphen, and optionally end with >. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | Webhook created successfully |
| 400 | Invalid input data |
| 500 | Internal server error |

**Response Examples:**

**400 (parse_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] could not parse json"
}
```

**400 (validation_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid webhook request, details:[0-webhook.url must be provided]"
}
```

**400 (subscription_overlap):**

```json
{
  "code": 400,
  "message": "[Bad Request] subscription keys cannot overlap"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not create webhook"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "url": "https://example.com/webhook",
         "token": "my-token",
         "secret": "my-secret",
         "enabled": true,
         "subscriptions": [
         "filesystem.file.create",
         "filesystem.>"
       ]
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/webhooks"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "url": "https://example.com/webhook",
  "token": "my-token",
  "secret": "my-secret",
  "enabled": true,
  "subscriptions": [
  "filesystem.file.create",
  "filesystem.>"
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /webhooks/{id}

**Summary:** Get a specific webhook

Retrieves a specific webhook by its ID

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the webhook |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Webhook retrieved successfully |
| 400 | Invalid input data |
| 404 | Webhook is not found |
| 500 | Internal server error |

**Response Examples:**

**400 (id_required):**

```json
{
  "code": 400,
  "message": "[Bad Request] id is required"
}
```

**400 (invalid_uuid):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid uuid format"
}
```

**404:**

```json
{
  "code": 404,
  "message": "[Not Found] webhook is not found"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not get webhook"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/webhooks/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the webhook

url = f"https://{{instance}}.kiteworks.com/webhooks/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## PUT /webhooks/{id}

**Summary:** Update a webhook

Updates an existing webhook

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the webhook |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `url` | string | yes | URL contains the webhook URL |
| `token` | string | no | Token contains the webhook Token (optional; if provided must not be empty or whitespace-only) |
| `secret` | string | yes | Secret contains the webhook Secret |
| `enabled` | boolean | no | Enabled is the value of the webhook enable/disable (default is true when omitted) |
| `subscriptions` | string[] | yes | Subscriptions is a list of NATS subject filter patterns associated with the webhook. Each entry must be non-empty and contain only letters, numbers, dot, asterisk, underscore, hyphen, and optionally end with >. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Webhook updated successfully |
| 400 | Invalid input data |
| 404 | Not found - webhook with Id could not be found |
| 409 | Conflict - webhook instance is modified since operation started |
| 500 | Internal server error |

**Response Examples:**

**400 (id_required):**

```json
{
  "code": 400,
  "message": "[Bad Request] id is required"
}
```

**400 (invalid_uuid):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid uuid format"
}
```

**400 (parse_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] could not parse json"
}
```

**400 (validation_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid webhook request, details:[0-webhook.url must be provided]"
}
```

**400 (subscription_overlap):**

```json
{
  "code": 400,
  "message": "[Bad Request] subscription keys cannot overlap"
}
```

**404:**

```json
{
  "code": 404,
  "message": "[Not Found] webhook is not found"
}
```

**409:**

```json
{
  "code": 409,
  "message": "[Conflict] webhook instance has been changed since update"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not update webhook"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/webhooks/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "url": "https://example.com/webhook",
         "token": "my-token",
         "secret": "my-secret",
         "enabled": true,
         "subscriptions": [
         "filesystem.file.create",
         "filesystem.>"
       ]
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the webhook

url = f"https://{{instance}}.kiteworks.com/webhooks/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "url": "https://example.com/webhook",
  "token": "my-token",
  "secret": "my-secret",
  "enabled": true,
  "subscriptions": [
  "filesystem.file.create",
  "filesystem.>"
]
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## PATCH /webhooks/{id}

**Summary:** Partially update a webhook

Updates specific fields of an existing webhook without requiring all fields to be present

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the webhook |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `url` | string | no | URL contains the webhook URL |
| `token` | string | no | Token contains the webhook Token (if provided must not be empty or whitespace-only) |
| `secret` | string | no | Secret contains the webhook Secret |
| `enabled` | boolean | no | Enabled is the value of the webhook enable/disable |
| `subscriptions` | string[] | no | Subscriptions is a list of NATS subject filter patterns associated with the webhook. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Webhook updated successfully |
| 400 | Invalid input data |
| 404 | Not found - webhook with Id could not be found |
| 409 | Conflict - webhook instance is modified since operation started |
| 500 | Internal server error |

**Response Examples:**

**400 (id_required):**

```json
{
  "code": 400,
  "message": "[Bad Request] id is required"
}
```

**400 (invalid_uuid):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid uuid format"
}
```

**400 (parse_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] could not parse json"
}
```

**400 (validation_error):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid webhook request, details:[0-webhook.url must be provided]"
}
```

**400 (subscription_overlap):**

```json
{
  "code": 400,
  "message": "[Bad Request] subscription keys cannot overlap"
}
```

**404:**

```json
{
  "code": 404,
  "message": "[Not Found] webhook is not found"
}
```

**409:**

```json
{
  "code": 409,
  "message": "[Conflict] webhook instance has been changed since update"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not patch webhook"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PATCH \
  "https://{instance}.kiteworks.com/webhooks/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "url": "https://example.com/webhook",
         "token": "my-token",
         "secret": "my-secret",
         "enabled": true,
         "subscriptions": [
         "filesystem.file.create",
         "filesystem.>"
       ]
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the webhook

url = f"https://{{instance}}.kiteworks.com/webhooks/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "url": "https://example.com/webhook",
  "token": "my-token",
  "secret": "my-secret",
  "enabled": true,
  "subscriptions": [
  "filesystem.file.create",
  "filesystem.>"
]
}
response = requests.patch(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /webhooks/{id}

**Summary:** Delete a webhook

Deletes an existing webhook by its ID

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the webhook |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Webhook deleted successfully |
| 400 | Invalid input data (missing or invalid ID) |
| 404 | Not Found |
| 500 | Internal server error |

**Response Examples:**

**400 (id_required):**

```json
{
  "code": 400,
  "message": "[Bad Request] id is required"
}
```

**400 (invalid_uuid):**

```json
{
  "code": 400,
  "message": "[Bad Request] invalid uuid format"
}
```

**404:**

```json
{
  "code": 404,
  "message": "[Not Found] webhook is not found"
}
```

**500:**

```json
{
  "code": 500,
  "message": "[Internal Server Error] could not delete webhook"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/webhooks/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the webhook

url = f"https://{{instance}}.kiteworks.com/webhooks/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---