VSKI v0.2.0

Features

Enhanced Webhook System

• Retry Configuration: Configure retry limits (1-100 attempts, default 5) for all webhooks

  • Set retry limit per webhook for fine-grained control
  • Configurable via collection triggers, standalone webhooks, and cron jobs
  • Limits prevent runaway retry loops

• Exponential Backoff Retry Mechanism:

  • Retry delay increases exponentially: 2^0=2s, 2^1=4s, 2^2=8s, 2^3=16s, 2^4=32s
  • Prevents hammering downstream services during outages
  • Reduces network load and server stress

• JWT Authentication for Webhooks:

  • Optional JWT bearer tokens for webhook authentication
  • Tokens include roles: ["service", "webhook"] for easy server-side verification
  • Enable per-webhook for secure integrations

• Restart-Proof Webhook Execution:

  • Webhook state persisted in _webhook_logs table
  • Automatic retry continuation after server restart
  • No lost webhook deliveries during deployments

Standalone Webhook Management

• CRUD API for Standalone Webhooks:

  • Create, read, update, delete standalone webhooks
  • Manage webhooks independent of collections
  • Useful for external integrations and scheduled tasks

• Webhook Manager Service:

  • Dedicated service for webhook lifecycle management
  • Centralized webhook execution logic
  • Consistent behavior across all webhook sources

• Webhook Registry in Database:

  • New webhooks table stores webhook configurations
  • Fields: name, url, method, headers, body, retryLimit, jwtEnabled, active
  • Persistent storage survives server restarts

Cron Job Integration

• Unified Webhook Execution:

  • Cron HTTP callbacks now use webhook service
  • Same retry logic and logging as collection webhooks
  • Consistent experience across all webhook types

• Enhanced Cron Configuration:

  • Configure retry limit for HTTP cron jobs
  • Enable JWT auth for authenticated HTTP callbacks
  • Custom headers for request authentication
  • Request body for POST/PUT/PATCH methods

• One-Time Execution:

  • New once flag for cron jobs
  • When once: true, job is automatically deleted after successful execution
  • Perfect for scheduled one-time tasks or delayed execution
  • Works with both SQL and HTTP cron jobs

• Cron Job Updates:

  • New PATCH /api/cron/:name endpoint for updating existing cron jobs
  • Update schedule, command, and once flag without recreating the job
  • Cron scheduler automatically reloads updated job configuration
  • Frontend edit modal reuses the create form with pre-populated data

Docker Enhancements

• Standalone Docker Image:

  • New Docker image with embedded web UI (vski:standalone)
  • Multi-stage build process using denoland/deno:2.6.6 official image
  • Web frontend built and embedded during Docker build
  • No need to build web frontend separately

• Docker Build Automation:

  • New docker-build-standalone make target for building standalone image
  • New docker-push-standalone make target for pushing standalone image
  • Automatic copying of web source from ../web/ before build
  • Versioned and latest tags automatically applied

• Release Process Integration:

  • Both light and standalone images built and pushed during release
  • Consistent tagging across image variants ({VERSION}, latest)
  • Automated via release.ts script

Frontend Enhancements

• Updated Cron Settings UI:

  • Retry limit configuration (1-100, default 5)
  • JWT auth toggle for HTTP jobs
  • Custom headers input (JSON format)
  • Request body configuration
  • “Delete after successful execution” (once) checkbox

• Webhooks Manager Page (/settings/webhooks):

  • List all standalone webhooks
  • Create/edit/delete webhooks
  • Manual webhook trigger for testing
  • Status indicators (active/inactive)

Client SDK Updates

• Enhanced Trigger Config Types:

  • retryLimit: number (optional)
  • jwtEnabled: boolean (optional)
  • method: string (optional)
  • headers: Record<string, string> (optional)

• New Webhook Types:

  • Webhook: Standalone webhook configuration
  • CreateWebhookRequest: Input for creating webhooks
  • UpdateWebhookRequest: Input for updating webhooks

• Webhooks Namespace:

  • sdk.webhooks.list(): List all webhooks
  • sdk.webhooks.get(id): Get webhook by ID
  • sdk.webhooks.create(data): Create new webhook
  • sdk.webhooks.update(id, data): Update webhook -sdk.webhooks.delete(id)`: Delete webhook
  • sdk.webhooks.trigger(id): Manually trigger webhook

Backend API Endpoints

• Standalone Webhook Management:

  • GET /api/webhooks - List all webhooks
  • GET /api/webhooks/:id - Get webhook details
  • POST /api/webhooks - Create webhook
  • PUT/PATCH /api/webhooks/:id - Update webhook
  • DELETE /api/webhooks/:id - Delete webhook
  • POST /api/webhooks/:id/trigger - Manually trigger webhook

• Cron Job Management:

  • GET /api/cron - List all cron jobs
  • POST /api/cron - Create new cron job
  • PATCH /api/cron/:name - Update existing cron job
  • DELETE /api/cron/:name - Delete cron job

• JWT Token Generation:

  • New GenerateTokenWithRoles(id, roles, tokenKey) method
  • Supports custom role claims (e.g., ["service", "webhook"])
  • Used by webhook service for authenticated requests

Database Schema Changes

• New webhooks Table:

  CREATE TABLE webhooks (
    id TEXT PRIMARY KEY,
    name TEXT UNIQUE NOT NULL,
    url TEXT NOT NULL,
    method TEXT DEFAULT 'POST',
    headers TEXT,
    body TEXT,
    retryLimit INTEGER DEFAULT 5,
    jwtEnabled BOOLEAN DEFAULT 0,
    active BOOLEAN DEFAULT 1,
    created TEXT DEFAULT (datetime('now')),
    updated TEXT DEFAULT (datetime('now'))
  );

• Updated cron_jobs Table:

  ALTER TABLE cron_jobs ADD COLUMN once BOOLEAN DEFAULT FALSE;

  • Added once column for one-time execution flag
  • Default value is false (recurring jobs)

Installation

Binary

Download binary for your platform:

# Linux (standalone with embedded UI)
wget https://vski.sh/x/platform/releases/download/v0.2.0/vski-standalone
chmod +x vski-standalone
./vski-standalone

# Linux (API-only)
wget https://vski.sh/x/platform/releases/download/v0.2.0/vski
chmod +x vski
./vski

Docker

Pull and run official Docker image:

# Light version (API only, no embedded UI)
docker pull vski.sh/x/vski:latest

# Standalone version (with embedded web UI)
docker pull vski.sh/x/vski:latest-standalone

# Pull specific version
docker pull vski.sh/x/vski:v0.2.0
docker pull vski.sh/x/vski:v0.2.0-standalone

# Run light version with default configuration
docker run -p 3000:3000 -v $(pwd)/data:/app/data vski.sh/x/vski:latest

# Run standalone version with embedded web UI
docker run -p 3000:3000 -v $(pwd)/data:/app/data vski.sh/x/vski:latest-standalone

# Run with custom environment variables
docker run -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e SERVER_PORT=3000 \
  -e DATA_DIR=/app/data \
  vski.sh/x/vski:latest-standalone

Configuration

Create a .env file:

DATA_DIR=./data
SERVER_PORT=3000
JWT_SECRET=your-secret-key

Usage

Configuring Collection Triggers with Enhanced Options

await client.settings.collections.update(collectionId, {
  options: JSON.stringify({
    triggers: [
      {
        action: "create",
        url: "https://your-endpoint.com/webhook",
        method: "POST",
        headers: {
          "Authorization": "Bearer token",
          "X-Custom-Header": "value"
        },
        retryLimit: 5,        // Maximum retry attempts
        jwtEnabled: true       // Include JWT bearer token
      }
    ]
  })
});

Creating Standalone Webhooks

// Create a new webhook
const webhook = await client.webhooks.create({
  name: "notification-service",
  url: "https://api.example.com/notify",
  method: "POST",
  headers: JSON.stringify({
    "Authorization": "Bearer your-token",
    "X-Source": "rocketbase"
  }),
  body: JSON.stringify({
    "message": "Hello from webhook"
  }),
  retryLimit: 3,
  jwtEnabled: true,
  active: true
});

// List all webhooks
const webhooks = await client.webhooks.list();

// Update a webhook
await client.webhooks.update(webhook.id, {
  retryLimit: 10,
  active: false
});

// Delete a webhook
await client.webhooks.delete(webhook.id);

// Manually trigger a webhook for testing
await client.webhooks.trigger(webhook.id);

Configuring Cron Jobs with Webhook Options

// Create HTTP cron job with retry and JWT
await client.cron.create({
  name: "daily_report",
  schedule: "0 9 * * *",      // 9 AM daily
  type: "http",
  url: "https://api.example.com/reports/daily",
  method: "POST",
  body: '{"report_type": "daily"}',
  headers: JSON.stringify({
    "X-Report-Auth": "secret-key"
  }),
  retryLimit: 5,
  jwtEnabled: true
});

// Create one-time cron job (deletes after successful execution)
await client.cron.create({
  name: "send_welcome_email",
  schedule: "*/5 * * * *",     // Run in 5 minutes
  type: "http",
  url: "https://api.example.com/send-email",
  method: "POST",
  body: JSON.stringify({
    "to": "user@example.com",
    "template": "welcome"
  }),
  once: true                   // Delete after execution
});

// Update an existing cron job
await client.cron.update("daily_report", {
  schedule: "0 8 * * *",       // Change schedule to 8 AM
  retryLimit: 10,              // Increase retry limit
  jwtEnabled: true             // Enable JWT authentication
});

Webhook Retry Behavior

Webhooks now retry with exponential backoff:

Attempt	Delay	Description
1	0s	Initial attempt
2	2s	First retry
3	4s	Second retry
4	8s	Third retry
5	16s	Fourth retry
6	32s	Fifth retry (if limit 5)

After exceeding retryLimit, webhook status is set to failed.

JWT Token Format

When jwtEnabled: true, webhooks include a JWT bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c2VzdmUzIiwid2ViZCIsInR5c2VyX3dlYmhvb2siLCJleHAiOjE3OTY1MzY5MywiaWF0IjoxNzA4NDM2NjkzfQ.abc123...

Token claims:

{
  "id": "webhook-service",
  "roles": ["service", "webhook"],
  "tokenKey": "webhook-token",
  "exp": 1739843693
}

Querying Webhook Logs

// Filter by collection and status
const logs = await client.webhookLogs.list({
  collection: "posts",
  status: "success"
});

// Logs include retry information
const log = logs[0];
console.log(`Tries: ${log.tries} / ${log.retryLimit || 5}`);
console.log(`Status: ${log.status}`);

Migration Notes

Database Migration

The webhooks table is automatically created on server startup. No manual migration required.

Breaking Changes

None. This release is fully backward compatible.

Configuration Updates

Existing webhook configurations will continue to work with default values:

• retryLimit: Defaults to 5 if not specified
• jwtEnabled: Defaults to false if not specified
• method: Defaults to POST if not specified

API Endpoints

Standalone Webhooks

Method	Endpoint	Description
GET	/api/webhooks	List all webhooks
GET	/api/webhooks/:id	Get webhook by ID
POST	/api/webhooks	Create new webhook
PUT	/api/webhooks/:id	Update webhook
PATCH	/api/webhooks/:id	Partially update webhook
DELETE	/api/webhooks/:id	Delete webhook
POST	/api/webhooks/:id/trigger	Manually trigger webhook

Webhook Logs

Method	Endpoint	Query Params	Description
GET	/api/webhooks/logs	collection, status, page, perPage	Query webhook delivery logs

Testing

Run E2E Tests

cd vski
make build
make e2e TEST=19_webhooks_test.ts  # Test webhook triggers
make e2e TEST=10_cron_test.ts       # Test cron integration

Documentation

Full documentation available at: https://vski.sh/x/platform

Changelog

v0.2.0 (2026-02-17)

Added

• Retry limit configuration (1-100, default 5)
• Exponential backoff retry mechanism (2^n seconds)
• JWT authentication for webhooks with service,webhook roles
• Standalone webhook CRUD API and management UI
• Cron HTTP job integration with webhook service
• Webhook Manager Service for unified webhook handling
• Webhooks client namespace for SDK
• One-time execution flag (once) for cron jobs
• Automatic deletion of cron jobs with once: true after successful execution
• Cron job update API (PATCH /api/cron/:name) for modifying existing jobs
• Cron job edit UI in frontend with pre-populated form data
• Docker standalone image with embedded web UI (vski:standalone)
• Multi-stage Docker build process for standalone version
• Docker build automation targets (docker-build-standalone, docker-push-standalone)

Changed

• Cron HTTP jobs now use webhook service instead of direct HTTP calls
• Enhanced retry logic from fixed 5 attempts to configurable limit
• Retry delay increased from 5s to 2s initial with exponential growth
• Docker build process now supports both light and standalone variants

Fixed

• Webhook state now persists across server restarts
• Consistent logging for all webhook types (triggers, cron, standalone)