SSE & Webhooks

• Live stream (SSE). Hold an outbound GET /api/stream open and we push changes down it. No inbound port to expose: it’s a normal long-lived HTTPS request with your API key. See Live stream below.
• Webhook. We POST each change to an HTTPS URL you host.

​

Live stream (SSE)

curl -N https://www.serializedaudit.io/api/stream -H "X-Auth-Key: $KEY"

event: ready
data: {"since": 766042}

event: audit.changed
id: 766083
data: { "type": "audit.changed", "chain": "ROBINHOOD", "audit": { ... }, "diff": { ... }, ... }

• Resume with no gaps. On reconnect, send the last id back. The browser EventSource does it automatically via Last-Event-ID; from code, pass the header or ?since=<id>. We replay every event after it, so a dropped connection never loses a change. A fresh connect (no id) streams new events only; ?since=0 replays your whole history.
• It’s scoped to your active subscriptions, exactly like a webhook and /events.
• Keepalive. We send a : comment every ~25s so proxies keep the connection open. Reconnect on any disconnect (add your own backoff).
• Both at once is fine. If you also have a webhook set, you’ll receive each change on both, so dedupe on event_id.

const es = new EventSource('https://www.serializedaudit.io/api/stream', {
  headers: { 'X-Auth-Key': KEY },   // server-side EventSource libs support headers
})
es.addEventListener('audit.changed', (e) => update(JSON.parse(e.data)))
// reconnection + Last-Event-ID resume are automatic

​

Set up a webhook

curl -X PUT https://www.serializedaudit.io/api/webhook \
  -H "X-Auth-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"url":"https://your-backend.example.com/serialized-webhook"}'
# -> { "ok": true, "url": "...", "secret": "whsec_..." }

{
  "webhook_url": "https://your-backend.example.com/serialized-webhook",
  "has_secret": true,
  "deliveries_24h": { "delivered": 128, "pending": 2, "dead": 1 },
  "subscriptions": 1543
}

​

Subscribe tokens

# one, or bulk (up to 5000)
curl -X POST https://www.serializedaudit.io/api/subscriptions \
  -H "X-Auth-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"tokens":[{"chain":"ROBINHOOD","address":"0x..."}]}'

{ "dry_run": true, "window_days": 15, "current_version_only": true,
  "would_subscribe": 1543, "credits_per_token": 2, "credits_required": 3086,
  "confirm_required": true, "hint": "POST again with ?confirm=true to subscribe and be charged." }

​

The event you receive

{
  "type": "audit.changed",
  "event_id": "a816aafb-...",
  "chain": "ROBINHOOD", "address": "0x...", "audit_id": 766083,
  "created_at": "2026-07-24T18:46:59.000Z",
  "change": {
    "is_safe": { "before": true, "after": false, "changed": true },
    "owner_changed": false,
    "vulns": { "added": 1, "removed": 0, "changed": 0 }
  },
  "audit": { "isSafe": false, "vulnerabilities": [ ], "name": "…", "sourceType": "verified", "…": "…" },
  "diff": { "added": [ ], "removed": [ ], "changed": [ ] }
}

• audit is the complete new verdict: the exact same object you get back from /audit-contract for this token. Do store[address] = payload.audit and you’re done; no re-fetch. (It’s null only if the change left no audit, e.g. a manual lock removed.)
• change is a compact summary for cheap routing/alerting (badge flips, “a critical was added”) without parsing the full verdict.
• diff tells you which findings moved: added / removed are full vuln objects, changed is { before, after, fields }.

​

Verify the webhook signature

import crypto from 'node:crypto'
function verify(rawBody: string, header: string, secret: string): boolean {
  const m = /t=(\d+),v1=([0-9a-f]+)/.exec(header || '')
  if (!m) return false
  const [, t, v1] = m
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(v1)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

​

Delivery guarantees

• At-least-once. We retry once (~30s after the first failure) on any non-2xx/timeout, then dead-letter. A push can arrive more than once, so dedupe on event_id.
• Respond 2xx fast (10s timeout, webhook). Verify → enqueue → 200; do your work async.
• Nothing is lost. Every change is written to a durable outbox. Replay anything you missed: GET /api/events?since=<last_id>&limit=1000 → { "events": [...], "cursor": <id> }. Page with since=cursor. This is your catch-up path after downtime (and what the stream’s Last-Event-ID resume draws on). /events is scoped to your currently-active subscriptions: unsubscribing a token (DELETE) also hides its past events from replay, so drain what you need before unsubscribing. Each element is the same audit.changed object shown above, plus an id — the sequential paging id. cursor is the id of the last element (a number, echoing since on an empty page).
  { "events": [ { "id": 406045, "type": "audit.changed", "event_id": "8067cc0a-…", "…": "…" } ],
    "cursor": 406045 }
  
  since means the opposite here than on the stream. On /api/events, omitting since is the same as since=0 and replays your whole history from the beginning. On /api/stream, omitting it gives you new events only. In practice, always call /api/events with since=<the last id you processed>.
• We pace webhook delivery (~3 pushes/sec to one endpoint), so a big initial catch-up is spread out, never dumped at once. Steady-state is well under 1/sec.

​

Endpoints