casset/docs
FeaturesOpen app
docs indexreference
00Overview01Thesis02Architecture03System reality04Roadmap05Investor brief06Technical brief07Full tech HTML08Casset Apps09Headless API10Playback11Audio pipeline12Commerce13Base anchoring14Hook system15Music video16Theming17Creator guide18Glossary
Headless APIDeployed · unsupported
QuickstartExamplesAPI ReferenceSDK
Advanced
React adapterStarter detailsError handlingRetries & timeoutsUse casesRequest IDs & safe loggingAPI versioningLocal sandboxLocal webhooksAvailability & limitationsFAQChangelogDesign principles
Headless API · Local webhooks

Practice delivery semantics on one machine.

The sandbox signs credential-revocation events, retries bounded transient failures, supports replay, and suppresses receiver duplicates. Every part is development-only.

Durable production subscriptions, delivery, retry, replay, and audit history are unavailable. There is no deployed public webhook endpoint or production signing secret.

Local rehearsal only

Subscription URLs must be explicit loopback HTTP(S) URLs with no credentials, query string, or fragment. The signing secret is revealed once and must never appear in logs, tickets, fixtures, or browser code.

Implemented event

Local webhook contract
FieldCurrent valueMeaning
schemacasset.webhook-event.v1Exact event body schema.
typecredential.revokedThe only emitted event type.
apiVersion2026-07-19.sandboxLocal sandbox event version.
BodyImmutable JSON for one event IDReplay preserves the same event and exact body.

Delivery headers

  • x-casset-event-id — immutable event identifier.
  • x-casset-delivery-id — new for each original delivery or replay.
  • x-casset-webhook-id — identifies the local subscription inside the sandbox.
  • x-casset-signature — t=<timestamp>,v1=<sha256-hmac>.

These identifiers may be used inside the local receiver's duplicate logic, but they are not a recommendation to log App IDs, credential prefixes, webhook secrets, exact bodies, or receiver query strings.

Verify before parsing

  1. Read at most 128 KiB of UTF-8 request data.
  2. Parse the signature header and reject timestamps outside the five-minute window.
  3. Compute HMAC-SHA256 over timestamp + "." + exactBody.
  4. Compare the signature in constant time.
  5. Only then parse the exact event schema and compare body/header identifiers.

Exact bytes matter

Whitespace, newline, or serialization changes alter the signed body and fail verification. Verify the bytes received, not a parsed-and-reserialized object.

Retry policy

Local webhook delivery outcomes
OutcomeRetryRecorded outcome
2xxNoSUCCESS
408, 425, 429, or 500+YesHTTP_TRANSIENT
Other non-2xxNoHTTP_TERMINAL
Network failureYesNETWORK
No response within 2 secondsYesTIMEOUT
  • Maximum three total attempts.
  • Two-second timeout per attempt.
  • Deterministic waits of 25 ms and then 50 ms.
  • No production-scale delivery guarantee is implied.

Replay and duplicate suppression

Replay keeps the event ID and exact body, then creates a new delivery ID. The receiver returns whether it has already seen that delivery or event. Concurrent replay requests with one idempotency key resolve to one local delivery result.

Read Retries to compare webhook behavior with SDK GET retries, or Sandbox for one-time credentials and revocation.

© Casset 2026
Trust & PrivacyTerms