HBMHBM Rocket
ALL DOCS
DOCUMENTATION

API and webhooks

8 MIN READ

Programmatic access to your HBM Rocket org. Manage sites, trigger audits, fetch results, deliver events to your own systems.

Base URL and authentication

https://speed.homebuildermarketers.com/api/v1

Pass a personal token as a Bearer header on every request.

curl https://speed.homebuildermarketers.com/api/v1/sites \
  -H "Authorization: Bearer rkt_live_<your_token>"

Tokens are scoped at creation time. The default scopes are sites:read, audits:read. Add audits:write to trigger reoptimizations, sites:write to create or update sites.

Endpoints (selected)

List sites

GET /v1/sites

Response 200:
{
  "sites": [
    {
      "id": "cmoq...",
      "name": "Summit Construction Utah",
      "hostname": "summitconstructionutah.com",
      "status": "HEALTHY",
      "audits": [...]
    }
  ]
}

Get a site with audits and events

GET /v1/sites/{id}

Trigger reoptimization

POST /v1/sites/{id}/reoptimize

Response 200:
{ "ok": true, "queued": 4 }

This queues a critical CSS regeneration, an unused CSS scan, and fresh Lighthouse audits for both strategies.

List audits across the org

GET /v1/audits-list?limit=60

System health

GET /v1/system

Rate limits

  • 1000 requests per minute per token, sliding window
  • 20 reoptimization triggers per site per hour
  • 5 site creations per minute

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are returned on every response.

Webhooks

Outbound webhooks deliver events when something changes. Configure under Optimize → Integrations.

Event types

  • site.added when a site is created
  • audit.completed after each Lighthouse run
  • audit.regression when a metric drops past target
  • alert.opened and alert.resolved
  • artifact.published when critical CSS or unused CSS regenerates

Signature

Every webhook is HMAC SHA256 signed with a secret you configure. Verify the signature in your handler before trusting the body.

X-Rocket-Webhook-Timestamp: 1714750000
X-Rocket-Webhook-Signature: <hex digest>

# Server side verification (Node example)
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(timestamp + '.' + body)
  .digest('hex');
if (expected !== signature) reject();
Webhook delivery retries with exponential backoff up to 5 attempts. Endpoints that return non-2xx are paused after 30 consecutive failures and you receive an email.

Errors

Errors return a JSON envelope with stable codes. Common codes:

  • auth_required 401
  • auth_invalid 401
  • rate_limited 429
  • not_found 404
  • conflict 409 (e.g., duplicate hostname)
  • internal_error 500
API and webhooks | HBM Rocket