Webhooks

Setup

Create an endpoint at app.quackstack.fyi/settings/webhooks. We sign every delivery with HMAC-SHA256 in the X-Quackstack-Signature header.

Events

• quack.created — a new session started
• quack.completed — session ended (timeout or :done)
• quack.shared — a session was shared externally
• quota.exceeded — monthly allowance hit
• quota.warning — 80% of allowance used

Payload

json{
  "id": "evt_8h2j",
  "type": "quack.completed",
  "created": 1717200000,
  "data": {
    "quack_id": "qk_4f1a",
    "user_id": "usr_zzz",
    "duration_ms": 12480,
    "messages": 8
  }
}

Verifying signatures

typescriptimport { createHmac, timingSafeEqual } from "crypto";

function verify(body: string, sig: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Retries

We retry failed deliveries with exponential backoff over 24 hours. Respond with any 2xx within 5s to acknowledge.