Webhooks - Hooper API

Register an HTTPS endpoint and Hooper POSTs an event to it when a session finishes. The event carries the full session object, so a single delivery gives you the highlights, shots and box score.

Events

`type`	When	`data.object`
`session.processed`	Processing finished successfully	The session, with `highlights` / `shots` / `players` populated
`session.failed`	Processing failed (or timed out)	The session with `status: "failed"` and `error` set; nothing was charged

{
  "id": "evt_91", "object": "event", "type": "session.processed", "created": 1756224000,
  "data": { "object": { "id": "sess_18234", "object": "session", "status": "processed", "…": "…" } }
}

Registering an endpoint

curl https://api.hooper.gg/v1/webhook_endpoints \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/hooper", "enabled_events": ["*"] }'

The response includes "secret": "hws_prod_…" — shown once, so store it now. Send a synthetic event to check your handler with POST /v1/webhook_endpoints/we_2/test.

Verifying signatures

Every delivery carries:

Hooper-Signature: t=1756224000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e146c8a0…
Hooper-Event-Id: evt_91

v1 is HMAC-SHA256(secret, "{t}.{raw_body}"). This is the same scheme Stripe uses, so an existing Stripe verifier works with the secret swapped. Verify before you parse, using the raw request body, and reject timestamps older than 5 minutes.

import hmac, hashlib, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig) and abs(time.time() - ts) <= tolerance

# FastAPI / Flask etc.
if not verify(HOOPER_WEBHOOK_SECRET, request_body_bytes, request.headers["Hooper-Signature"]):
    return Response(status=400)

import crypto from "node:crypto";

export function verify(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  return ok && Math.abs(Date.now() / 1000 - ts) <= tolerance;
}
// Express: use express.raw({ type: "application/json" }) so req.body is the raw bytes.

import stripe
# Same algorithm: Stripe's verifier accepts Hooper's header with Hooper's secret.
stripe.WebhookSignature.verify_header(raw_body, sig_header, HOOPER_WEBHOOK_SECRET, tolerance=300)

Delivery semantics

Acknowledge with any 2xx. Do it fast; process asynchronously.
At-least-once. Retries happen on any non-2xx or timeout (10 s): after 1m, 5m, 30m, 2h, 6h, 12h, 24h — eight attempts over about two days. Dedupe on the event id.
Auto-disable. An endpoint that has been failing for 7 straight days is disabled; re-create it when fixed.
Catch-up. Missed something? GET /v1/events?type=session.processed&created[gte]=… lists every event, newest first.

Endpoint requirements

Public https:// URL, no credentials in the URL, resolving to a public address. Private, loopback and link-local destinations are rejected at registration.