API Reference
Complete REST API specification for managing tunnels, retrieving webhook logs, and orchestrating projects programmatically.
Available API Endpoints
All API requests target https://api.hookcheck.dev/v1. Responses are JSON-encoded with standard HTTP status codes. Rate limit: 120 requests per minute per API key.
GET /tunnels
List all active and archived tunnels for the authenticated project. Supports pagination via ?page=&limit= query parameters. Returns tunnel ID, status, assigned hostname, creation timestamp, and total captured event count.
POST /tunnels
Create a new tunnel. Body requires {"name": string, "region": "eu-west-1" | "us-east-1"}. Returns the tunnel's unique ID, public URL (e.g., https://abc123.hookcheck.dev), and an initial WebSocket handshake token.
GET /tunnels/:id/logs
Retrieve captured webhook events for a specific tunnel. Filter by HTTP method, status code range, or timestamp window using ?method=POST&status=2xx&since=2024-06-01T00:00:00Z. Each log entry includes the full request body, headers, and response payload.
DELETE /tunnels/:id
Permanently delete a tunnel and all associated logs. Irreversible. Returns 200 OK with {"deleted": true, "tunnel_id": "..."} on success. Returns 404 if the tunnel does not exist.
GET /projects
List all projects accessible to the authenticated user. Each project object contains id, name, plan (free, pro, team), tunnel_count, and created_at.
GET /projects/:id/webhooks
List outbound webhook subscriptions configured for a project. Each subscription includes the target URL, event types (e.g., tunnel.created, log.captured), retry policy, and last delivery status.
Authenticate Your Requests
HookCheck uses Bearer token authentication. Include your API key in the Authorization header on every request. Keys are scoped to a single project and can be rotated from the Dashboard settings.
Header Format
Send the key as a Bearer token: Authorization: Bearer hc_live_sk_7f3a9b2c1d4e8f6a5b0c9d2e1f3a4b5c. Test keys prefixed with hc_test_sk_ are sandbox-scoped and never trigger real webhooks.
Key Rotation
Rotating a key immediately invalidates the previous one. A 24-hour grace window is provided for in-flight requests. Use POST /api-keys with {"expires_at": "2025-12-31"} to set an explicit expiry.
Error Responses
Invalid or expired keys return 401 Unauthorized with {"error": "invalid_api_key", "message": "The provided key does not exist or has been revoked."}. Missing headers return 401 with "missing_api_key".
API Usage Examples
Copy-paste ready curl commands for the most common operations. Replace the placeholder API key and tunnel ID with your own values.
Create a Tunnel
curl -X POST https://api.hookcheck.dev/v1/tunnels \
-H "Authorization: Bearer hc_live_sk_7f3a9b2c1d4e8f6a5b0c9d2e1f3a4b5c" \
-H "Content-Type: application/json" \
-d '{"name": "stripe-checkout-test", "region": "eu-west-1"}'
Response: {"id": "tun_9x8y7z6w5v", "url": "https://9x8y7z6w5v.hookcheck.dev", "status": "active", "created_at": "2024-11-14T09:32:11Z"}
Fetch Tunnel Logs
curl https://api.hookcheck.dev/v1/tunnels/tun_9x8y7z6w5v/logs?page=1&limit=25 \
-H "Authorization: Bearer hc_live_sk_7f3a9b2c1d4e8f6a5b0c9d2e1f3a4b5c"
Returns an array of log objects with id, method, path, status_code, request_body, response_body, and captured_at.
List All Projects
curl https://api.hookcheck.dev/v1/projects \
-H "Authorization: Bearer hc_live_sk_7f3a9b2c1d4e8f6a5b0c9d2e1f3a4b5c"
Response: {"projects": [{"id": "proj_abc123", "name": "Acme Checkout", "plan": "pro", "tunnel_count": 4, "created_at": "2024-03-18T14:00:00Z"}]}