Quickstart

From zero to your first highlights in three requests.

You need an API key (hk_prod_…) from your Hooper contact and a public HTTPS URL that can receive webhooks.

1. Register a webhook 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" }'
   

   The response includes "secret": "hws_prod_…" exactly once — store it. You’ll use it to verify deliveries.

2. Submit a video

   The simplest source is a public Veo match page or an HTTPS link to an MP4:

   curl https://api.hooper.gg/v1/sessions \
     -H "Authorization: Bearer $HOOPER_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: match-abc-123" \
     -d '{
       "source": { "url": "https://app.veo.co/matches/20260826-acme-vs-north/" },
       "metadata": { "external_match_id": "abc-123" },
       "options": { "session_type": "5v5" }
     }'
   

   {
     "id": "sess_18234", "object": "session", "status": "queued",
     "metadata": { "external_match_id": "abc-123" },
     "highlights": { "object": "list", "data": [], "has_more": false, "total_count": 0, "url": "/v1/sessions/sess_18234/highlights" },
     "...": "..."
   }
   

   The X-Hooper-Cost-Cents header tells you what was held. To upload your own file instead, see Sessions → Sources.

3. Receive the result

   Minutes to an hour later (depending on length), your endpoint receives:

   {
     "id": "evt_91", "object": "event", "type": "session.processed", "created": 1756224000,
     "data": { "object": {
       "id": "sess_18234", "status": "processed", "duration_seconds": 5412, "cost_cents": 752,
       "highlights": { "object": "list", "total_count": 42, "data": [ { "id": "hl_9f2c", "player": "plr_5", "video": { "1080p": "https://…" } } ] },
       "shots":      { "object": "list", "total_count": 118, "data": [ "..." ] },
       "players":    { "object": "list", "total_count": 10,  "data": [ { "id": "plr_5", "name": "Ana", "stats": { "points": 22 } } ] },
       "totals":     { "points": 88, "...": "..." }
     } }
   }
   

   Verify the Hooper-Signature header before trusting it — see Webhooks. Prefer polling? GET /v1/sessions/sess_18234 returns the same object.

Use metadata to carry your own ids. It is echoed on the session and inside every event, so you never need a mapping table.