webhook API — Kiteworks Developer Portal

GET/webhooks

Get all webhooks

Retrieves a list of all webhooks with optional pagination

Parameters

Query Parameters

offset

Optional

integer

Offset value (must be 0 or a positive integer)

limit

Optional

integer

Limit count (must be 0 or a positive integer)

Responses

Webhooks retrieved successfully

items

Required

WebhookResponse[]

Items is the list of webhook items in the current set

id

Required

string

Id is the unique identifier for the webhook.

url

Required

string

URL contains the webhook URL

enabled

Required

boolean

Enabled is the value of the webhook enable/disable

createdAt

Required

string

CreatedAt is the timestamp when the webhook was created.

updatedAt

Required

string

UpdatedAt is the timestamp when the webhook was last updated.

subscriptions

Required

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

status

Required

Status

Status is a status data associated with the webhook.

status

Required

string

Status value

description

Required

string

Status description

totalItems

Required

integer

TotalItems is the total number of items across all sets

Invalid pagination parameters

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Shell

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

Python

import requests

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

Responses

{ "items": [ { "id": "1a51a2bf-86e8-40e8-a53b-4edc6936db46", "url": "https://example.com/webhook", "enabled": true, "createdAt": "2024-05-07T15:04:05Z", "updatedAt": "2024-05-07T15:04:05Z", "subscriptions": [ "filesystem.file.create", "filesystem.>" ] } ], "totalItems": 150 }

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

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

POST/webhooks

Create a new webhook

Creates a new webhook based on the body content

Request Body

Webhook payload

url

Required

string

URL contains the webhook URL

token

string

Token contains the webhook Token (optional; if provided must not be empty or whitespace-only)

secret

Required

string

Secret contains the webhook Secret

enabled

boolean

Enabled is the value of the webhook enable/disable (default is true when omitted)

subscriptions

Required

string[]

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

Webhook created successfully

id

Required

string

Id is the unique identifier for the webhook.

url

Required

string

URL contains the webhook URL

enabled

Required

boolean

Enabled is the value of the webhook enable/disable

createdAt

Required

string

CreatedAt is the timestamp when the webhook was created.

updatedAt

Required

string

UpdatedAt is the timestamp when the webhook was last updated.

subscriptions

Required

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

status

Required

Status

Status is a status data associated with the webhook.

status

Required

string

Status value

description

Required

string

Status description

Invalid input data

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

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

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())

Responses

{ "id": "1a51a2bf-86e8-40e8-a53b-4edc6936db46", "url": "https://example.com/webhook", "enabled": true, "createdAt": "2024-05-07T15:04:05Z", "updatedAt": "2024-05-07T15:04:05Z", "subscriptions": [ "filesystem.file.create", "filesystem.>" ] }

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

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

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

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

GET/webhooks/{id}

Get a specific webhook

Retrieves a specific webhook by its ID

Parameters

Path Parameters

id

Required

string

ID of the webhook

Responses

Webhook retrieved successfully

id

Required

string

Id is the unique identifier for the webhook.

url

Required

string

URL contains the webhook URL

enabled

Required

boolean

Enabled is the value of the webhook enable/disable

createdAt

Required

string

CreatedAt is the timestamp when the webhook was created.

updatedAt

Required

string

UpdatedAt is the timestamp when the webhook was last updated.

subscriptions

Required

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

status

Required

Status

Status is a status data associated with the webhook.

status

Required

string

Status value

description

Required

string

Status description

Invalid input data

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Webhook is not found

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Shell

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

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())

Responses

{ "id": "1a51a2bf-86e8-40e8-a53b-4edc6936db46", "url": "https://example.com/webhook", "enabled": true, "createdAt": "2024-05-07T15:04:05Z", "updatedAt": "2024-05-07T15:04:05Z", "subscriptions": [ "filesystem.file.create", "filesystem.>" ] }

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

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

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

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

PUT/webhooks/{id}

Update a webhook

Updates an existing webhook

Parameters

Path Parameters

id

Required

string

ID of the webhook

Request Body

Updated webhook payload

url

Required

string

URL contains the webhook URL

token

string

Token contains the webhook Token (optional; if provided must not be empty or whitespace-only)

secret

Required

string

Secret contains the webhook Secret

enabled

boolean

Enabled is the value of the webhook enable/disable (default is true when omitted)

subscriptions

Required

string[]

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

Webhook updated successfully

id

Required

string

Id is the unique identifier for the webhook.

url

Required

string

URL contains the webhook URL

enabled

Required

boolean

Enabled is the value of the webhook enable/disable

createdAt

Required

string

CreatedAt is the timestamp when the webhook was created.

updatedAt

Required

string

UpdatedAt is the timestamp when the webhook was last updated.

subscriptions

Required

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

status

Required

Status

Status is a status data associated with the webhook.

status

Required

string

Status value

description

Required

string

Status description

Invalid input data

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Not found - webhook with Id could not be found

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Conflict - webhook instance is modified since operation started

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

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

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())

Responses

{ "id": "1a51a2bf-86e8-40e8-a53b-4edc6936db46", "url": "https://example.com/webhook", "enabled": true, "createdAt": "2024-05-07T15:04:05Z", "updatedAt": "2024-05-07T15:04:05Z", "subscriptions": [ "filesystem.file.create", "filesystem.>" ] }

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

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

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

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

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

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

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

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

PATCH/webhooks/{id}

Partially update a webhook

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

Parameters

Path Parameters

id

Required

string

ID of the webhook

Request Body

Partial webhook payload with only the fields to update

url

string

URL contains the webhook URL

token

string

Token contains the webhook Token (if provided must not be empty or whitespace-only)

secret

string

Secret contains the webhook Secret

enabled

boolean

Enabled is the value of the webhook enable/disable

subscriptions

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

Responses

Webhook updated successfully

id

Required

string

Id is the unique identifier for the webhook.

url

Required

string

URL contains the webhook URL

enabled

Required

boolean

Enabled is the value of the webhook enable/disable

createdAt

Required

string

CreatedAt is the timestamp when the webhook was created.

updatedAt

Required

string

UpdatedAt is the timestamp when the webhook was last updated.

subscriptions

Required

string[]

Subscriptions is a list of NATS subject filter patterns associated with the webhook.

status

Required

Status

Status is a status data associated with the webhook.

status

Required

string

Status value

description

Required

string

Status description

Invalid input data

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Not found - webhook with Id could not be found

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Conflict - webhook instance is modified since operation started

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

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

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())

Responses

{ "id": "1a51a2bf-86e8-40e8-a53b-4edc6936db46", "url": "https://example.com/webhook", "enabled": true, "createdAt": "2024-05-07T15:04:05Z", "updatedAt": "2024-05-07T15:04:05Z", "subscriptions": [ "filesystem.file.create", "filesystem.>" ] }

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

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

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

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

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

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

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

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

DELETE/webhooks/{id}

Delete a webhook

Deletes an existing webhook by its ID

Parameters

Path Parameters

id

Required

string

ID of the webhook

Responses

Webhook deleted successfully

Empty response body.

Invalid input data (missing or invalid ID)

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Not Found

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Internal server error

code

integer

Code is the HTTP status code returned by the API.

message

string

Message is a human-readable message in the format "[StatusText] detail" explaining the result.

Shell

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

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())

Responses

// Request successful - No Body

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

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

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

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