nansen-alerts-webhook-listener

What this skill does

# Alert Webhook Listener

Set up a local HTTP server to receive Nansen smart alert webhook payloads in real-time.

## How It Works

Nansen smart alerts support a **webhook** channel type. When an alert fires, Nansen sends an HTTP POST with a JSON payload to your webhook URL. This skill sets up:

1. A local HTTP server (Node.js, zero external dependencies) that receives and displays alert payloads
2. HMAC-SHA256 signature verification so only authentic Nansen payloads are accepted
3. A public tunnel so Nansen's servers can reach your local machine

**This skill does NOT create or modify alerts.** It sets up the listener infrastructure and then provides a summary of what the user needs to do to start receiving alerts.

**OpenClaw users:** If OpenClaw is running locally on the same machine, the webhook server can forward verified alert payloads to OpenClaw's Gateway (`/hooks/agent`), triggering an agent turn for each alert. Set the `OPENCLAW_GATEWAY_URL` env var to enable this. See the **OpenClaw Integration** section below.

## Security Warning

**Before proceeding, inform the user:**

> This skill starts an HTTP server on your machine and exposes it to the internet via a tunnel (ngrok or localtunnel). While the server only binds to localhost (`127.0.0.1`) — meaning no one on your local network can access it directly — the tunnel creates a public URL that **anyone on the internet** can send requests to.
>
> **Mitigations in place:**
> - HMAC-SHA256 signature verification rejects all requests not signed by Nansen
> - 1 MB body size limit prevents memory abuse
> - Only `POST /webhook` and `GET /health` are accepted; everything else returns 404
>
> **You should be aware that:**
> - The tunnel URL is publicly discoverable (ngrok URLs can be enumerated)
> - Unsigned requests still reach your machine — they're rejected, but the connection is made
> - Stop the tunnel when you're done to close the public endpoint

Wait for the user to confirm they want to proceed before continuing.

## Execution Plan

Follow these steps **in order**. Do not skip signature verification — it is mandatory.

### Step 0: Choose a tunnel provider

Before starting, ask the user which tunnel provider they want to use:

| | **ngrok** (recommended) | **localtunnel** |
|---|---|---|
| Stability | Stable — persistent connections with keepalive | Flaky — free relay drops idle connections without warning, tunnels die randomly |
| Install | `brew install ngrok` + free account at ngrok.com | Zero install (`npx localtunnel`) |
| HTTPS | Yes | Yes |
| Auth required | Yes (free authtoken from ngrok.com) | No |

**Recommend ngrok.** localtunnel is convenient but unreliable — in testing, tunnels silently exit after minutes, causing alerts to fail with "503 Tunnel Unavailable". ngrok maintains stable connections.

Check if ngrok is available:
```bash
which ngrok && ngrok version
```

If not installed, tell the user:
1. `brew install ngrok` (or download from ngrok.com)
2. Create a free account at ngrok.com and copy the authtoken
3. `ngrok config add-authtoken <token>`

If the user prefers localtunnel or can't install ngrok, proceed with localtunnel but warn them that the tunnel may drop and they'll need to restart it and update their alert's webhook URL.

### Step 1: Generate a webhook secret

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Store the output — you need it for both the server and the alert configuration. **Never log or echo the secret after this point.**

### Step 2: Write the webhook receiver script

Create `nansen-webhook-server.mjs` in the current working directory. Use **only** Node.js built-in modules (`node:http`, `node:crypto`). No `npm install` required.

**Requirements — do not deviate:**

| Requirement | Detail |
|---|---|
| Bind address | `127.0.0.1` only — **never** `0.0.0.0` |
| Default port | `9477` (override via `PORT` env var) |
| Webhook path | `POST /webhook` — reject all other method/path combos with 404 |
| Health check | `GET /health` → 200 `{"status":"ok"}` |
| Signature verification | Verify `x-nansen-signature` header using HMAC-SHA256 with timing-safe comparison. Reject 401 on mismatch. |
| Secret validation | Exit on startup if `WEBHOOK_SECRET` env var is missing or < 16 chars |
| Payload logging | Pretty-print valid JSON payloads to stdout with ISO timestamp |
| Request size limit | Reject bodies > 1 MB (413) to prevent memory abuse |
| Graceful shutdown | Handle `SIGINT` and `SIGTERM` — close server, then exit |
| OpenClaw forwarding | If `OPENCLAW_GATEWAY_URL` env var is set, forward verified payloads to `<url>/hooks/agent` via POST. Include `OPENCLAW_AUTH_TOKEN` as Bearer token if set. Log forward success/failure. |
| No dependencies | Only `node:http`, `node:https`, and `node:crypto` — nothing from npm |

**Signature verification — use timing-safe comparison:**

```javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifySignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  // Nansen sends "sha256=<hex>" — strip the prefix before comparing
  const sig = signatureHeader.startsWith('sha256=') ? signatureHeader.slice(7) : signatureHeader;
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'));
  } catch {
    return false; // length mismatch
  }
}
```

**Full server template:**

```javascript
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const PORT = parseInt(process.env.PORT || '9477', 10);
const SECRET = process.env.WEBHOOK_SECRET;
const MAX_BODY = 1_048_576; // 1 MB

// Optional: forward verified payloads to a local OpenClaw Gateway
const OPENCLAW_URL = process.env.OPENCLAW_GATEWAY_URL; // e.g. http://localhost:3000
const OPENCLAW_TOKEN = process.env.OPENCLAW_AUTH_TOKEN;

if (!SECRET || SECRET.length < 16) {
  console.error('WEBHOOK_SECRET env var required (minimum 16 characters).');
  console.error('Generate one: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"');
  process.exit(1);
}

function verifySignature(rawBody, signatureHeader) {
  if (!signatureHeader) return false;
  // Nansen sends "sha256=<hex>" — strip the prefix before comparing
  const sig = signatureHeader.startsWith('sha256=') ? signatureHeader.slice(7) : signatureHeader;
  const expected = createHmac('sha256', SECRET).update(rawBody).digest('hex');
  try {
    return timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'));
  } catch {
    return false;
  }
}

async function forwardToOpenClaw(payload) {
  if (!OPENCLAW_URL) return;
  const url = `${OPENCLAW_URL.replace(/\/+$/, '')}/hooks/agent`;
  const headers = { 'Content-Type': 'application/json' };
  if (OPENCLAW_TOKEN) headers['Authorization'] = `Bearer ${OPENCLAW_TOKEN}`;
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers,
      body: JSON.stringify(payload),
    });
    if (res.ok) {
      console.log(`[${ts()}] Forwarded to OpenClaw (${res.status})`);
    } else {
      console.error(`[${ts()}] OpenClaw forward failed (${res.status})`);
    }
  } catch (err) {
    console.error(`[${ts()}] OpenClaw forward error: ${err.message}`);
  }
}

function ts() { return new Date().toISOString(); }

const server = createServer((req, res) => {
  if (req.method === 'GET' && req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    return res.end('{"status":"ok"}');
  }

  if (req.method !== 'POST' || req.url !== '/webhook') {
    res.writeHead(404);
    return res.end();
  }

  let size = 0;
  const chunks = [];

  req.on('data', (chunk) => {
    size += chunk.length;
    if (size > MAX_BODY) {
      res.writeHead(413);
      res.end('{"error":"Payload too large"}');
      req.destroy();
      return;
    }
    chunks.push(chunk);
  });

  req.on('end', ()