{"name":"The Leo King Business Intelligence API Webhook Contract","version":"v1","status":"release-gate","contractVersion":"2026-07-09.enterprise-trust-paid-route-ci-gate-v1","lastReviewedAt":"2026-07-09","delivery":{"transport":"HTTPS POST","contentType":"application/json","signatureHeader":"TheLeoKing-Signature","signingStatus":"worker-ready-activation-gated","idempotency":"Use the event id as the webhook idempotency key.","note":"The delivery queue and internal drain worker exist behind ops auth; partner-facing activation requires approved endpoint configuration, Convex deployment, and delivery smoke."},"signature":{"header":"TheLeoKing-Signature","scheme":"v1","algorithm":"HMAC-SHA256","signedPayload":"timestamp.raw_body","headerFormat":"t=,v1=","timestampToleranceSeconds":300,"exampleHeader":"TheLeoKing-Signature: t=1783394100,v1=3e7f4f0d8f9a0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566778899aa","verificationSteps":["Read the raw request body before JSON parsing.","Parse `t` and one or more `v1` signatures from `TheLeoKing-Signature`.","Reject timestamps outside the 300 second replay window.","Compute `HMAC-SHA256(secret, `${t}.${rawBody}`)` and compare against each `v1` value using constant-time comparison.","Deduplicate accepted events by event id before applying side effects."],"replayProtection":"Reject timestamps outside the tolerance window and persist event ids so retries cannot create duplicate side effects.","secretHandling":"Store endpoint secrets in a backend secret manager. Never log the secret, full signature, or raw private payload.","deliveryStatus":"Verification contract, internal delivery worker, retry queue, and dead-letter storage are ready behind the ops gate; partner-facing activation still requires approved endpoint configuration and deploy smoke."},"events":[{"event":"world_signal.job.completed","status":"release_gate","category":"async_job","description":"A long-running world-signal forecast job finished and passed quality gates.","delivery":"Signed HTTPS POST","when":"After async job completion and usage write confirmation.","payload":["id","type","created_at","request_id","job_id","status","data","usage","meta"],"idempotency":"Use event id as the webhook idempotency key.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Exponential retry with dead-letter visibility after final failure."},{"event":"world_signal.job.failed","status":"release_gate","category":"async_job","description":"A long-running world-signal forecast job failed before producing a billable result.","delivery":"Signed HTTPS POST","when":"After terminal failed status is written.","payload":["id","type","created_at","request_id","job_id","status","error"],"idempotency":"Use event id as the webhook idempotency key.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Exponential retry with dead-letter visibility after final failure."},{"event":"usage.recorded","status":"release_gate","category":"usage","description":"A successful billable API call wrote usage metadata for partner reconciliation.","delivery":"Signed HTTPS POST","when":"After the usage ledger accepts the request event.","payload":["id","type","created_at","request_id","endpoint","lane","credits","model","tokens"],"idempotency":"Deduplicate on request_id plus event type.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Retry only after ledger write succeeds; failed partner delivery does not create duplicate usage."},{"event":"quality.failed","status":"release_gate","category":"quality","description":"A generative endpoint failed a quality or schema gate and should not be shown or billed.","delivery":"Signed HTTPS POST","when":"After model/schema/output validation fails for an AI route.","payload":["id","type","created_at","request_id","endpoint","quality_gate","error"],"idempotency":"Deduplicate on request_id plus quality_gate.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Low retry count because this is diagnostic, not a user deliverable."},{"event":"entitlement.updated","status":"enterprise","category":"entitlement","description":"A workspace plan, scoped key, endpoint allowance, or custom limit changed.","delivery":"Signed HTTPS POST","when":"After customer entitlement state is committed.","payload":["id","type","created_at","organization_id","plan","endpoint_access","limits"],"idempotency":"Deduplicate on event id and organization id.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Retry until partner acknowledges or event moves to dead letter."},{"event":"billing.subscription.updated","status":"enterprise","category":"billing","description":"A customer subscription, renewal, cancellation, or invoice state changed.","delivery":"Signed HTTPS POST","when":"After billing provider webhook processing updates local entitlement state.","payload":["id","type","created_at","organization_id","subscription_status","plan","effective_at"],"idempotency":"Deduplicate on provider event id plus organization id.","signature":"TheLeoKing-Signature: t=,v1=.","retryPolicy":"Retry after internal billing state is consistent."}],"links":{"docs":"/api-docs","trust":"/trust","product":"/api-platform","console":"/api-console","lab":"/api-console/lab","billing":"/api-console/billing","index":"/api/v1","openapi":"/api/v1/openapi","status":"/api/v1/status","sla":"/api/v1/sla","incidents":"/api/v1/incidents","security":"/api/v1/security","securityTxt":"/.well-known/security.txt","accessControl":"/api/v1/access-control","observability":"/api/v1/observability","onboarding":"/api/v1/onboarding","versioning":"/api/v1/versioning","examples":"/api/v1/examples","support":"/api/v1/support","sdks":"/api/v1/sdks","migrations":"/api/v1/migrations","procurement":"/api/v1/procurement","conformance":"/api/v1/conformance","dataProcessing":"/api/v1/data-processing","compliance":"/api/v1/compliance","aiGovernance":"/api/v1/ai-governance","changelog":"/api/v1/changelog","webhooks":"/api/v1/webhooks","errors":"/api/v1/errors","postman":"/api/v1/postman","readiness":"/api/v1/ops/readiness?deep=1","llms":"/llms.txt","llmsFull":"/llms-full.txt"}}