Debug & Testing Tools
Interactive tools for testing webhook endpoints, verifying security, and diagnosing latency.
Token Vault includes built-in debug tools for webhook mode users. Access them from the Debug hub in the navigation bar, or go directly to /debug in the dashboard.
Webhook Endpoint Tester
The endpoint tester at /debug/webhook lets you test each webhook endpoint individually or run a full automated workflow.
Available Endpoint Tests
| Test | Endpoint | What It Verifies |
|---|---|---|
| Health Check | GET/POST /v1/health | Webhook is reachable and reports healthy status |
| Storage List | POST /v1/storage (list) | Can list tokens, audit events, proxy configs, vault config |
| Storage Get | POST /v1/storage (get) | Can retrieve a single item from a collection |
| Storage Batch | POST /v1/storage (list_batch) | Can fetch multiple collections in one call |
| Storage Set | POST /v1/storage (set) | Can write test data to a collection |
| Storage Delete | POST /v1/storage (delete) | Can remove items (requires confirmation) |
| Refresh Get | POST /v1/refresh (get) | TV-mediated refresh Phase 1 works (requires tv-refresh capability) |
| Forged Credential Ticket | GET /v1/credential | Webhook rejects tickets signed with wrong HMAC key |
| Real Ticket from TV IP | GET /v1/credential | Webhook rejects requests from Token Vault's IP |
| Forged Store Ticket | POST /v1/store | Webhook rejects store tickets with wrong HMAC key |
Each test shows the full HTTP request and response, with secrets masked. Schema validation checks that responses match the expected format. Per-call latency is measured and colour-coded: green (< 200ms), yellow (< 500ms), red (> 500ms).
Full Workflow Test
The "Test All" button runs an automated sequence that exercises the entire webhook protocol:
- Health check -verify the webhook is reachable.
- List tokens -fetch current token metadata.
- Write test data -create a test entry in the
tokenscollection. - Read back -retrieve the test entry and validate the response schema.
- Batch list -fetch tokens and audit collections in one call.
- Security tests -run forged ticket and IP filtering tests.
- Delete test data -clean up the test entry.
- Verify cleanup -confirm the test entry no longer appears in listings.
Safe to run
The Full Workflow Test creates and cleans up its own test data (prefixed with __tv_test_). It does not modify your real tokens or credentials.
Results are saved and displayed on the vault settings page via the Webhook Test Results card, showing pass/fail/warning status for each step with the total latency.
Security Tests
Three security tests verify your webhook correctly rejects unauthorized requests. See the Security page for detailed explanations of each test and why they matter.
| Test | Expected Result | If It Fails |
|---|---|---|
| Forged Credential Ticket | 401 Rejected | Any attacker could bypass Token Vault and steal credentials |
| Real Ticket from TV IP | Rejected (warning if accepted) | No network-level zero-knowledge isolation |
| Forged Store Ticket | 401 Rejected | Attackers could overwrite stored credentials |
Latency Diagnostics
The latency diagnostics page at /debug/latency simulates a full dashboard load and shows where time is spent.
Waterfall View
Every API call the dashboard makes is timed and displayed as a horizontal bar:
- Green (< 200ms) -fast, no action needed
- Yellow (< 500ms) -acceptable, but could be optimised
- Red (> 500ms) -slow, investigate your webhook or network
Phase Breakdown
Calls are grouped into phases:
- Server reads -agent, policy, grant, and user document lookups (parallelised)
- Webhook calls -individual
/v1/storagecalls for tokens, audit, vault config - Batch calls -single
/v1/storagelist_batchcall (if supported)
The summary shows total backend time, browser round-trip, and a verdict identifying whether server or webhook latency is the bottleneck.
System Overview
The diagnostics page also displays:
- Current vault configuration and webhook status
- Webhook capabilities (including
tv-refresh) - Last 5 audit events with timestamps
Backend API Reference
These endpoints power the debug tools and can be called directly for automation:
| Endpoint | Method | Description |
|---|---|---|
/api/vault/webhook/test-endpoint | POST | Test a single webhook endpoint |
/api/vault/webhook/test-all | POST | Run the full workflow test |
/api/webhook/test-results | GET | Retrieve the last saved test-all results |
Security
URL validation requirements, the kill switch mechanism, and security best practices for your webhook service.
Deploy Your Own Webhook with ngrok
Step-by-step guide to deploying a Token Vault webhook server locally using Docker and ngrok, binding it to your vault, and storing your first credential.