Skip to content

Webhooks

Jump to bottom
Chris edited this page Jul 25, 2026 · 4 revisions

Webhooks

KV Manager delivers robust webhook notifications for key lifecycle events and bulk operations, empowering you to build powerful event-driven architectures. Seamlessly configure webhooks to dispatch real-time HTTP POST requests to external systems like Slack, Discord, or your custom monitoring endpoints.

Overview

Webhooks allow you to:

  • Receive real-time notifications when KV operations occur
  • Integrate with external monitoring and alerting systems
  • Trigger automated workflows based on key events
  • Track failures and issues proactively

Using the Webhook Manager UI

KV Manager includes a full-featured webhook management interface accessible from the main navigation:

  1. Navigate to Webhooks - Click the "Webhooks" tab in the main navigation bar
  2. Create a Webhook - Click "Create Webhook" and fill in:
    • Name - A descriptive name for this webhook
    • URL - The endpoint URL to receive notifications
    • Secret (optional) - A secret for HMAC signature verification
    • Events - Select which events should trigger this webhook
  3. Manage Webhooks - From the webhook list, you can:
    • Toggle enabled/disabled - Click the switch to enable or disable
    • Edit - Click the edit icon to modify settings
    • Test - Click the test icon to send a test payload
    • Delete - Click the delete icon to remove the webhook

UI Features

  • Status Badges - Visual indicators showing enabled/disabled state
  • Event Count - Shows how many events are configured per webhook
  • Secret Indicator - Shield icon appears when HMAC signing is configured
  • Test Results - Immediate feedback showing success/failure with HTTP status codes

Supported Events

Key Events

Event Trigger
key_create Key created in namespace
key_update Key value updated
key_delete Key deleted from namespace

Bulk Operation Events

Event Trigger
bulk_delete_complete Bulk delete operation finished
bulk_copy_complete Bulk copy operation finished
bulk_ttl_complete Bulk TTL update finished
bulk_tag_complete Bulk tag operation finished

Import/Export Events

Event Trigger
import_complete Import operation finished
export_complete Export operation finished

Backup/Restore Events

Event Trigger
backup_complete R2 backup finished
restore_complete R2 restore finished

Job Events

Event Trigger
job_failed Any job failed
batch_complete Batch operation finished

Error Events

Event Trigger
error_critical Critical error occurred
error_warning Warning logged
error_info Info logged

Monitoring Events

Event Trigger
threshold.storage_usage Storage usage threshold exceeded
threshold.operation_rate Operation rate threshold exceeded
threshold.operation_latency Operation latency threshold exceeded
threshold.resolved Previously exceeded threshold has resolved
analytics.unavailable Analytics data is temporarily unavailable

Configuration

Using the API

Create Webhook

curl -X POST https://your-kv-manager.workers.dev/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/xxx/yyy/zzz",
    "secret": "my-secret",
    "events": ["key_create", "key_delete", "job_failed"],
    "enabled": true
  }'

List Webhooks

curl https://your-kv-manager.workers.dev/api/webhooks

Update Webhook

curl -X PUT https://your-kv-manager.workers.dev/api/webhooks/whk_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete Webhook

curl -X DELETE https://your-kv-manager.workers.dev/api/webhooks/whk_abc123

Test Webhook

curl -X POST https://your-kv-manager.workers.dev/api/webhooks/whk_abc123/test

Payload Format

All webhook payloads follow this structure:

{
  "event": "key_create",
  "timestamp": "YYYY-MM-DDTHH:MM:SS.000Z",
  "data": {
    "namespace_id": "abc-123",
    "key_name": "my-key",
    "user_email": "user@example.com"
  }
}

Headers

Header Description
Content-Type application/json
User-Agent KV-Manager-Webhook/1.0
X-Webhook-Event The event type (e.g., key_create)
X-Webhook-Signature HMAC-SHA256 signature (if secret is configured)

Security

HMAC Signature Verification

If you configure a secret for your webhook, KV Manager will include an X-Webhook-Signature header with each request. This allows you to verify that the request genuinely came from KV Manager.

Signature format: sha256=<hex-encoded-hmac>

Example verification (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSig = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  );
}

// In your webhook handler:
const isValid = verifyWebhookSignature(
  req.rawBody,
  req.headers['x-webhook-signature'],
  'your-webhook-secret'
);

Database Schema

Webhooks are stored in the webhooks table in the metadata database:

CREATE TABLE IF NOT EXISTS webhooks (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  url TEXT NOT NULL,
  secret TEXT,
  events TEXT NOT NULL, -- JSON array of event types
  enabled INTEGER DEFAULT 1,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Migration

For existing installations, run the specific migration to add the webhooks table:

npx wrangler d1 execute YOUR_DATABASE_NAME --remote --file=worker/migrations/add_webhooks.sql

Replace YOUR_DATABASE_NAME with your actual D1 database name (e.g., my-kv-metadata).

The migration is idempotent - safe to run multiple times. If the webhooks table already exists, the migration will succeed without errors.

Troubleshooting

Webhook not firing

  1. Check that the webhook is Enabled
  2. Verify the event type is in the webhook's events list
  3. Use the Test endpoint to check connectivity
  4. Check your endpoint's logs for incoming requests

Signature verification failing

  1. Ensure you're using the raw request body (not parsed JSON)
  2. Verify the secret matches exactly
  3. Check for encoding issues with special characters

Timeout errors

Webhook requests have a timeout. If your endpoint takes too long to respond:

  • Return a 2xx status quickly, then process asynchronously
  • Optimize your endpoint's response time
  • Consider using a queue for heavy processing

See also:

Home

Getting Started

User Documentation

Technical

Guides

Links

Clone this wiki locally