docs(webhooks): add webhook intro, narrative flow between pages, and API reference callouts

yanxue06 · yanxue06 · commit 1b9c9a9e5bfa · 2026-05-15T12:27:38.000-07:00
diff --git a/docs-src/webhooks/events.mdx.vel b/docs-src/webhooks/events.mdx.vel
@@ -15,7 +15,7 @@ import { TypeTooltip } from "/snippets/type-tooltip.mdx";
    - `InboundMessage` is generic and the extractor returns an empty signature.
    The Space and User types are plain interfaces that extract cleanly. #}
 
-This page is the spec. Every webhook delivery is an HTTPS `POST` with a JSON body and four custom headers. The shape below is what your handler will see on every request.
+In the [Quickstart](/webhooks/quickstart), a real delivery flew past in `console.log`. This page is the spec — every header and every field your handler will see on every request, slowed down and labelled.
 
 The body's `space`, `message`, `sender`, and `content` fields are the same shapes you'd see from the [`spectrum-ts` SDK](/spectrum-ts/messages) — with one important difference: function-typed properties (`.read()`, `.stream()`, `.reply()`, `.react()`, etc.) are stripped before serialization, since functions can't survive `JSON.stringify`.
 
@@ -233,3 +233,16 @@ Required for idempotency
 Always returns 2xx fast
    Process asynchronously after acknowledging — see /webhooks/delivery
 ```
+
+## Where to next
+
+You now know exactly what arrives at your URL. The next two chapters cover *trusting* it and *handling failures* when something goes wrong.
+
+<Columns cols={2}>
+  <Card title="Verifying signatures" icon="shield-halved" href="/webhooks/verifying-signatures">
+    The four details every verifier has to get exactly right, with copy-paste implementations in four languages.
+  </Card>
+  <Card title="Delivery and retries" icon="repeat" href="/webhooks/delivery">
+    Retry policy, timeouts, idempotency, and what HTTP status codes mean to the worker.
+  </Card>
+</Columns>
diff --git a/webhooks/delivery.mdx b/webhooks/delivery.mdx
@@ -3,7 +3,7 @@ title: Delivery and retries
 description: How Spectrum decides when to retry, when to give up, and what your endpoint should return
 ---
 
-This page describes what happens *after* the worker computes a signature and starts the `POST` to your URL. The contract is simple but worth knowing exactly, because it determines how fault-tolerant you need to be on your end.
+You know what arrives ([Events](/webhooks/events)) and how to prove it's real ([Verifying signatures](/webhooks/verifying-signatures)). This page picks up the moment *after* the worker computes a signature and starts the `POST` to your URL — what it does when your server is fast, slow, broken, or unreachable. The contract is simple but worth knowing exactly, because it determines how fault-tolerant you need to be on your end.
 
 ## The contract in one paragraph
 
@@ -151,3 +151,16 @@ If your handler depends on order, sort by `message.timestamp` (which is the plat
 If you find yourself working hard to compensate for delivery loss, consider running [`spectrum-ts`](/spectrum-ts/getting-started) directly instead of (or in addition to) webhooks. The SDK's `instance.messages` async iterable is a long-lived stream — slower events can't be lost to a delivery timeout because there is no delivery, just a `for await` loop running in your process.
 
 A common pattern: webhooks for low-latency push, and a periodic reconciliation worker that uses the SDK or API to backfill anything the webhook layer missed.
+
+## Where to next
+
+With the contract clear, the remaining pages are operational. The next chapter is the day-to-day: managing the webhooks themselves.
+
+<Columns cols={2}>
+  <Card title="Managing webhooks" icon="gear" href="/webhooks/managing-webhooks">
+    Register, list, delete, and rotate signing secrets — each one testable in the [interactive API reference](/api-reference/introduction).
+  </Card>
+  <Card title="Troubleshooting" icon="bug" href="/webhooks/troubleshooting">
+    Common signature errors, missed deliveries, duplicates, and how to debug them.
+  </Card>
+</Columns>
diff --git a/webhooks/managing-webhooks.mdx b/webhooks/managing-webhooks.mdx
@@ -3,7 +3,13 @@ title: Managing webhooks
 description: Register, list, delete, and rotate webhook signing secrets via the Spectrum API
 ---
 
-You manage webhooks through three HTTP endpoints on the Spectrum API. All require `Basic` auth with your project credentials. The full OpenAPI reference lives under [API reference](/api-reference/introduction); this page focuses on the workflows.
+By now you can receive deliveries, verify them, and survive retries. This page is the operational layer — how you actually create the webhook records, list them, take one offline, or rotate a leaked secret.
+
+There are three HTTP endpoints, all under `https://spectrum.photon.codes/projects/{projectId}/webhooks/`. Every example below uses `curl`, but the same three endpoints are also live in the [interactive API reference](/api-reference/introduction) — paste your project credentials once and run any request from your browser.
+
+<Tip>
+**Read this page first, then hit the API reference.** This page explains *what* each endpoint does and *when* you'd reach for it; the API reference is the interactive playground for actually firing the request. The combo is much faster than reading either alone.
+</Tip>
 
 ## Authentication
 
@@ -212,3 +218,16 @@ This avoids any window where events go nowhere because the old URL has been dele
 2. Rotate every webhook signing secret using the delete-and-recreate flow above.
 
 The signing secret being leaked doesn't grant the attacker the ability to send messages on your behalf — only to forge inbound deliveries to your webhook URL. But in either case, rotating quickly is the right move.
+
+## Where to next
+
+You can register, list, delete, and rotate. If you're hitting a snag along the way — a verify that won't pass, a webhook that registers but never delivers, a duplicate that won't go away — the next chapter is the triage guide.
+
+<Columns cols={2}>
+  <Card title="Troubleshooting" icon="bug" href="/webhooks/troubleshooting">
+    Common signature errors, missed deliveries, duplicates, ngrok issues, and how to debug them.
+  </Card>
+  <Card title="API reference" icon="code" href="/api-reference/introduction">
+    The interactive playground for every endpoint on this page — run requests live from your browser.
+  </Card>
+</Columns>
diff --git a/webhooks/overview.mdx b/webhooks/overview.mdx
@@ -3,7 +3,13 @@ title: Webhooks
 description: Receive messaging events at your own URL — Spectrum signs each delivery so you know it's real
 ---
 
-Spectrum webhooks push platform events — incoming messages, and (soon) more — to a URL you control. You register the URL once, and from that moment on every message that lands for your project is delivered to your server as a signed HTTP `POST`.
+## What is a webhook?
+
+A webhook is the inverse of a normal API call.
+
+In a normal API call, your code reaches out and asks a service for data — you poll, you wait, you parse the response. In a *web*hook, the service reaches out to *you*: a message arrives, an event fires, and the service `POST`s the details to a URL you've published. You're not asking anymore; you're being told.
+
+For Spectrum, that means you write a regular HTTP handler — in whatever framework you already use — register its URL once, and from then on every inbound message across every enabled platform is delivered as a signed JSON `POST`. No long-lived process to babysit, no platform credentials in your runtime, no reconnect logic.
 
 ```ts
 const app = await Spectrum({ projectId, projectSecret, providers: [imessage.config()] });
@@ -21,7 +27,22 @@ X-Spectrum-Timestamp: 1747242392
 {"event":"messages","space":{...},"message":{...}}
 ```
 
-You write a normal HTTP handler in whatever framework you already use. Spectrum handles staying connected to every [supported platform](/spectrum-ts/providers), batching, reconnects, and signing.
+Spectrum handles staying connected to every [supported platform](/spectrum-ts/providers), batching, reconnects, and signing. You handle the HTTP request that lands at your door.
+
+## How this guide flows
+
+The next six pages build on each other. Skim straight to the topic you need, or read top-to-bottom in about fifteen minutes for the complete model.
+
+1. **[Quickstart](/webhooks/quickstart)** — register a URL, verify a signature, and receive your first real delivery in five minutes.
+2. **[Events](/webhooks/events)** — the exact wire format, every header and every field, with real examples.
+3. **[Verifying signatures](/webhooks/verifying-signatures)** — why the verifier looks the way it does, with copy-paste code in four languages.
+4. **[Delivery and retries](/webhooks/delivery)** — what happens when your endpoint is slow, down, or returns an unexpected status code.
+5. **[Managing webhooks](/webhooks/managing-webhooks)** — operate at scale: register, list, delete, and rotate signing secrets via the API or the dashboard.
+6. **[Troubleshooting](/webhooks/troubleshooting)** — common symptoms, root causes, and fixes when something goes wrong.
+
+<Tip>
+**Want to poke at the management endpoints before writing any code?** Every one of them is live in the [interactive API reference](/api-reference/introduction) — fill in your project credentials and run `List webhooks`, `Register webhook`, or `Delete webhook` straight from your browser. It's the fastest way to confirm credentials work and sanity-check a URL before wiring up a verifier.
+</Tip>
 
 ## When to use webhooks
 
@@ -77,7 +98,7 @@ The set will grow (reactions, typing indicators, custom provider events). New ev
 
 ## Security in one paragraph
 
-Each delivery includes an `X-Spectrum-Signature` header containing an HMAC-SHA256 of the request body, keyed by your per-webhook signing secret. Anyone can `POST` to your URL — only Spectrum can compute a signature that verifies. Recompute it on your side and reject anything that doesn't match. The full walkthrough, with copy-pasteable code in three languages, is on [Verifying signatures](/webhooks/verifying-signatures).
+Each delivery includes an `X-Spectrum-Signature` header containing an HMAC-SHA256 of the request body, keyed by your per-webhook signing secret. Anyone can `POST` to your URL — only Spectrum can compute a signature that verifies. Recompute it on your side and reject anything that doesn't match. The full walkthrough, with copy-pasteable code in four languages, is on [Verifying signatures](/webhooks/verifying-signatures).
 
 <Warning>
 Your signing secret is returned exactly once, in the response of `POST /webhooks/`. There is no "show me my secret" endpoint. Store it in your secret manager immediately. If you lose it, delete the webhook and re-register the URL — you'll get a new id and a new secret.
diff --git a/webhooks/quickstart.mdx b/webhooks/quickstart.mdx
@@ -3,7 +3,7 @@ title: Quickstart
 description: Register a URL, verify the signature, receive your first event in five minutes
 ---
 
-This walkthrough goes from "I have a Spectrum project" to "my server processed a real message" in about five minutes. We'll use Bun + Hono on the server side and [ngrok](https://ngrok.com/) to expose your local machine to the internet so you can test before deploying.
+The [Overview](/webhooks/overview) introduced the model — a service POSTing signed JSON to a URL you publish. This page makes it real. We'll go from "I have a Spectrum project" to "my server processed a real message" in about five minutes, using Bun + Hono on the server side and [ngrok](https://ngrok.com/) to expose your local machine to the internet so you can test before deploying.
 
 If you already have a deployed HTTPS URL, skip the ngrok step.
 
@@ -208,17 +208,19 @@ You verified each delivery is genuine (not spoofed), recent (not a replay), and
 
 ## What's next
 
+You wired up one URL, one verifier, and one delivery. The next chapters of the guide expand each piece — what's *in* the delivery, *why* the verifier looks the way it does, and what happens when things fail.
+
 <Columns cols={2}>
   <Card title="Events" icon="rss" href="/webhooks/events">
-    Every header and field in the payload, with examples.
+    Open the envelope — every header and every field in the payload, with examples for each content type.
+  </Card>
+  <Card title="Verifying signatures" icon="shield-halved" href="/webhooks/verifying-signatures">
+    The *why* behind the verifier, plus copy-paste implementations for Node, Bun, Python, and Go.
   </Card>
   <Card title="Delivery and retries" icon="repeat" href="/webhooks/delivery">
-    What happens when your endpoint is slow, down, or returns errors.
+    What the worker does when your endpoint is slow, down, or returns an unexpected status code.
   </Card>
   <Card title="Managing webhooks" icon="gear" href="/webhooks/managing-webhooks">
-    Listing, deleting, and rotating signing secrets via the API.
-  </Card>
-  <Card title="Troubleshooting" icon="bug" href="/webhooks/troubleshooting">
-    Common signature errors, missed deliveries, and how to debug them.
+    List, delete, and rotate signing secrets via the API — testable in the [interactive API reference](/api-reference/introduction).
   </Card>
 </Columns>
diff --git a/webhooks/troubleshooting.mdx b/webhooks/troubleshooting.mdx
@@ -3,7 +3,9 @@ title: Troubleshooting
 description: Common webhook problems, what they mean, and how to fix them
 ---
 
-This page is a triage guide for the most common things that go wrong with webhooks. Find the symptom, follow the fix.
+If you've followed the rest of this guide and something still isn't working, this is the page. It's organized by symptom — find what you're seeing in the headings below, follow the fix. Each section is self-contained, so you can land here from a search result and still get what you need.
+
+If your symptom isn't listed, jump to [Still stuck?](#still-stuck) at the bottom for what to send us so we can trace it on our side.
 
 ## "Every request fails signature verification"
 
diff --git a/webhooks/verifying-signatures.mdx b/webhooks/verifying-signatures.mdx
@@ -3,6 +3,8 @@ title: Verifying signatures
 description: Confirm each delivery is genuine, unmodified, and recent — copy-paste verifier code for Node, Bun, and Python
 ---
 
+You saw the verifier as a copy-paste in the [Quickstart](/webhooks/quickstart), and you saw the `X-Spectrum-Signature` header itself in [Events](/webhooks/events). This page is the *why* — what each line of that verifier is doing and how to port it to a different stack.
+
 Anyone on the internet can `POST` to your webhook URL. The signature is what tells you a request actually came from Spectrum and wasn't tampered with in transit. Skip this page only if you trust your network perimeter to do that for you — most production systems shouldn't.
 
 The recipe is small, but four details have to be exactly right or every legitimate request will be rejected. We cover each below.
@@ -311,3 +313,16 @@ export const verifyPhotonWebhook = (
 ```
 
 Pair it with the staleness check and you have a complete verifier.
+
+## Where to next
+
+A verified delivery is half the job. The other half is what your handler does with it — and what happens when your handler is slow, down, or buggy. That's the next chapter.
+
+<Columns cols={2}>
+  <Card title="Delivery and retries" icon="repeat" href="/webhooks/delivery">
+    Retry policy, timeouts, idempotency, and what every HTTP status code means to the worker.
+  </Card>
+  <Card title="Managing webhooks" icon="gear" href="/webhooks/managing-webhooks">
+    Operate at scale — register, list, delete, and rotate signing secrets (also testable in the [API reference](/api-reference/introduction)).
+  </Card>
+</Columns>
