Using API Keys

API keys let servers, scripts, or jobs receive webhook traffic over WebSocket without relying on the browser dashboard.

Caution

Plus includes API keys; Free does not.

Create a key in the web app

1. Sign in at hooknexus.com.
2. Open Settings → API Keys (or the equivalent in the current UI).
3. Click New Key (or similar).
4. Enter a name if prompted.
5. Copy the full key once — it is only shown at creation time. If you lose it, revoke the key and create another.

To revoke a key, use the same Settings screen — revoked keys stop working immediately and open WebSockets will disconnect.

Connect with WebSocket

wss://api.hooknexus.com/ws/{endpoint-id}?apikey={your-api-key}

API key auth currently uses the apikey query parameter on the URL, not an Authorization header.

This connection counts toward the endpoint’s shared WebSocket concurrency limit alongside dashboard and CLI listeners.

Full details and message formats are in the WebSocket API reference, and a fuller runnable sample is in the Node.js API key listener demo.

Node.js

const WebSocket = require('ws');
const endpointId = process.env.ENDPOINT_ID;
const apiKey = process.env.HOOKNEXUS_API_KEY;

const ws = new WebSocket(
  `wss://api.hooknexus.com/ws/${endpointId}?apikey=${encodeURIComponent(apiKey)}`
);

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === 'new_request') {
    console.log(msg.payload);
  }
  if (msg.type === 'replay_request') {
    console.log(msg.payload?.request);
  }
});

Python

import asyncio, json, websockets

async def listen():
    url = f"wss://api.hooknexus.com/ws/{ENDPOINT_ID}?apikey={API_KEY}"
    async with websockets.connect(url) as ws:
        async for msg in ws:
            data = json.loads(msg)
            if data.get("type") == "new_request":
                print(data.get("payload"))

asyncio.run(listen())

Typical limits (check the app)

Plan	API keys	WebSocket connections per endpoint
Free	—	2 (shared across dashboard, CLI, etc.)
Plus	1	3

Exact numbers are enforced for your account — see Pricing.

If your script only cares about live webhook traffic, ignore unknown message types and reconnect with backoff if the socket drops.

Security

1. Environment variables — e.g. export HOOKNEXUS_API_KEY="...".
2. One key per use case — easier to revoke if one script leaks.
3. Server-side only — never put keys in frontend bundles.
4. Rotate — revoke and recreate if you suspect exposure.