VSKI v0.1.0

Features

• Webhook Triggers: Configure automatic HTTP callbacks on record operations (create, update, delete)

  • Define webhooks per collection via collection options
  • Support for multiple webhooks per action
  • Custom HTTP methods (GET, POST, PUT, DELETE, PATCH)
  • Custom headers for authentication and metadata

• Webhook Execution & Logging:

  • Asynchronous webhook execution to avoid blocking operations
  • Comprehensive logging of all webhook attempts
  • Automatic retry mechanism (max 3 attempts with 5-second delay)
  • Detailed status tracking (pending, success, retrying, failed)

• Webhook Logs API:

  • Query webhook logs by collection and status
  • View full request/response details
  • Track retry attempts and error messages
  • Pagination support for large log sets

• Webhook Payload Structure:

  • Includes complete record data in webhook payload
  • Metadata: database name, collection name, record ID, action type, timestamp
  • JSON-formatted for easy parsing

Installation

Binary

Download binary for your platform:

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

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

Docker

Pull and run official Docker image:

# Pull latest version
docker pull vski.sh/x/vski:latest

# Pull specific version
docker pull vski.sh/x/vski:v0.1.0

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

# 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

Configuration

Create a .env file:

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

Usage

Configuring Webhooks

Webhooks are configured via collection options:

await client.settings.collections.update(collectionId, {
  options: JSON.stringify({
    triggers: [
      {
        action: "create",
        url: "https://your-endpoint.com/webhook",
        method: "POST",
        headers: {
          "Authorization": "Bearer your-token",
          "Content-Type": "application/json"
        }
      },
      {
        action: "update",
        url: "https://your-endpoint.com/webhook",
        method: "PATCH"
      },
      {
        action: "delete",
        url: "https://your-endpoint.com/webhook",
        method: "DELETE"
      }
    ]
  })
});

Webhook Payload Example

When a webhook is triggered, you’ll receive a JSON payload:

{
  "database": "default",
  "collection": "posts",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "action": "create",
  "timestamp": "2024-01-15T10:30:00Z",
  "record": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Hello World",
    "content": "My first post",
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-01-15T10:30:00Z"
  }
}

Viewing Webhook Logs

Query webhook logs via API:

const logs = await fetch('/api/webhooks/logs?collection=posts&status=success');
console.log(logs);

API Endpoints

GET /api/webhooks/logs

Query webhook logs with optional filters:

Query Parameters:

• collection - Filter by collection name
• status - Filter by status (pending, success, retrying, failed)
• page - Page number (default: 1)
• perPage - Items per page (default: 30, max: 100)

Response:

[
  {
    "id": "webhook-log-id",
    "url": "https://your-endpoint.com/webhook",
    "payload": { ... },
    "status": "success",
    "http_status": 200,
    "response_body": "...",
    "error_msg": null,
    "tries": 1,
    "created": "2024-01-15T10:30:00Z",
    "updated": "2024-01-15T10:30:05Z"
  }
]

Migration Notes

No database migration required. The _webhook_logs table is automatically created on first use.

Documentation

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