PubSub Quick Start

PubSub lets you receive real-time Kiteworks events at a URL of your choice. When something happens in your Kiteworks instance — a user logs in, a file is uploaded, a folder is shared — PubSub delivers that event as an HTTP POST to a webhook endpoint you register.

This guide walks you through registering a webhook and receiving your first event in under 15 minutes.

Prerequisites

Key concepts

Before you start, familiarise yourself with these three terms:

Subscription patterns use dot-separated subject syntax. A * matches exactly one segment; a > matches one or more trailing segments. For example:

Step 1: Register a webhook

The easiest way to register a webhook is through the Admin Portal UI — no API license required. In Admin Portal, go to Application Setup > Event Subscriptions and click + Add Webhook URL.

Fill in the following fields:

Click Save. The new webhook appears immediately in the Event Subscriptions list.

Step 2: Understand the event payload

Every delivery is a JSON POST with this envelope:

{
  "tenantId": "0",
  "webhookId": "1a51a2bf-86e8-40e8-a53b-4edc6936db46",
  "payload": {
    "event_name": "login",
    "user_id": 42,
    "username": "jane.doe@example.com",
    "ip_address": "203.0.113.5",
    "created": 1776039606.41,
    "tenant_id": 1,
    "host": "your-kiteworks-instance.com",
    "transaction_id": "WwbzN2nOcT5Qd2VjQIiKV374DvoUtbp9Gi3f4loBfuSKTk",
    "user_agent": "Mozilla/5.0 ...",
    "successful": true,
    "guid": "cad3c89d-36a1-44bd-b91f-14eba8aafecd"
  }
}

The outer envelope fields are:

Step 3: Build your webhook receiver

The examples below start a local HTTP server that accepts incoming POST requests and prints the event details.

from flask import Flask, request

app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def receive_event():
    event = request.get_json()
    print(f"Webhook:   {event['webhookId']}")
    print(f"Tenant:    {event['tenantId']}")
    print(f"Event:     {event['payload']['event_name']}")
    print(f"User:      {event['payload']['username']}")
    print(f"Successful:{event['payload']['successful']}")
    return "", 200


if __name__ == "__main__":
    app.run(port=3000)

import express, { Request, Response } from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req: Request, res: Response) => {
  const event = req.body;
  console.log("Webhook ID:", event.webhookId);
  console.log("Tenant ID: ", event.tenantId);
  console.log("Event:     ", event.payload.event_name);
  console.log("User:      ", event.payload.username);
  console.log("Successful:", event.payload.successful);
  res.status(200).send();
});

app.listen(3000, () => console.log("Receiver listening on port 3000"));

Start the server and — when a user on your Kiteworks instance logs in — you will see the event printed to your console.

Managing webhooks

All webhook management is available from Admin Portal > Application Setup > Event Subscriptions. The page lists every registered webhook with its URL, subscribed event categories, enabled/disabled toggle, and delivery status (Success or Error).

View registered webhooks

Open Application Setup > Event Subscriptions to see all webhooks. Each row shows the webhook URL, the event categories it is subscribed to, whether it is enabled, and its last delivery status.

API alternative (requires API license) — base path /pubsub-ext/webhooks: GET all webhooks · GET a specific webhook

Edit a webhook

Click the expand arrow on any row in the Event Subscriptions list to open the edit form. You can update the Webhook URL and change the subscribed event categories. You must keep at least one event category selected. Click Save to apply the changes or Cancel to discard them.

API alternative (requires API license): PUT (full update) · PATCH (partial update)

Enable or disable a webhook

Use the Enabled toggle on any row in the Event Subscriptions list to pause or resume deliveries without deleting the webhook.

API alternative (requires API license): PATCH webhook with {"enabled": false}

Delete a webhook

Click the Delete button on a webhook row in the Event Subscriptions list. This permanently removes the registration and stops all future deliveries to that URL.

API alternative (requires API license): DELETE webhook

Troubleshooting

I receive an HTML page instead of a JSON response

Your Kiteworks instance is running a version earlier than 9.4.0. PubSub is fully supported starting from Kiteworks Core 9.4.0. Contact your administrator to upgrade.

I receive HTTP 401 Unauthorized when calling the API

Your Kiteworks access token is missing, malformed, or expired. Confirm that your request includes Authorization: Bearer <token> in the request header and that the token is still valid. See Authentication for how to obtain or refresh a token.

My webhook is not receiving events

• Check it is enabled

  Open Application Setup > Event Subscriptions and confirm the Enabled toggle is on for your webhook.
• Check your subscription

  The * wildcard matches exactly one segment. events.user.* matches events.user.login but events.* does not — it does not match the third segment. Use events.> to match all events under events.
• Check your receiver is reachable

  Your Kiteworks instance must be able to reach your receiver over HTTPS. Use a tool like ngrok if you are running locally.
• Check your receiver returns 2xx

  Kiteworks retries non-2xx responses with exponential backoff: after 5 seconds, 5 minutes, 1 hour, then 1 day. If your server is returning an error code, the event will eventually be dropped after all retries are exhausted.

I am receiving the same event multiple times

PubSub has no duplicate detection — each webhook registration is independent. If you accidentally registered the same URL more than once, open Application Setup > Event Subscriptions, identify the duplicate entries by URL, and delete the extras using the Delete button.

I get an error about overlapping subscriptions when registering

PubSub enforces that no two webhooks can have overlapping subscription patterns across your entire account. For example, if one webhook already subscribes to all File/folder events, you cannot register another webhook for a specific nested file event — that subject is already covered. Either update the existing webhook to include the new event, or remove the broader subscription so you can add a more specific one.

I want to subscribe to all events

In the Add Webhook URL dialog, check Subscribe to all events at the top of the event category list. This subscribes the webhook to every event type. Be prepared for potentially high delivery volume.

Also see