Merge pull request #30 from photon-hq/spectrum-webhook-dashboard-mention

yanxue06 · web-flow · commit 51e28c44bf06 · 2026-05-15T13:48:26.000-07:00
docs(webhooks): developer-experience polish
diff --git a/docs-src/webhooks/events.mdx.vel b/docs-src/webhooks/events.mdx.vel
@@ -3,17 +3,11 @@ title: Events
 description: The exact wire format Spectrum sends — headers, body, and what each field contains
 ---
 
-import { TypeTooltip } from "/snippets/type-tooltip.mdx";
-
-{% set space = symbol("ts:spectrum-ts#Space") %}
-{% set user = symbol("ts:spectrum-ts#User") %}
-
-{# Note: We intentionally do NOT use TypeTooltip for `Content` or
-   `InboundMessage` because:
-   - `Content = z.infer<typeof contentSchema>` resolves to a Zod inference
-     reference that's unhelpful to customers.
-   - `InboundMessage` is generic and the extractor returns an empty signature.
-   The Space and User types are plain interfaces that extract cleanly. #}
+{# We deliberately do NOT use TypeTooltip on the Space/User/Message types here.
+   The SDK interfaces include methods (`.send()`, `.edit()`, `.getMessage()`,
+   etc.) that don't survive `JSON.stringify` — showing them as the type of a
+   webhook payload field is actively misleading. The serialized shapes on the
+   wire are simpler: `{ id, platform }` for Space and User. #}
 
 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.
 
@@ -92,8 +86,8 @@ This is the only event currently emitted. It fires once per inbound message that
 | Field | Type | Description |
 | --- | --- | --- |
 | `event` | `"messages"` | Discriminator. Always `"messages"` for this payload. |
-| `space` | <TypeTooltip name="Space" type={`{{ space.signature }}`} /> | The conversation context. See [Space](#space) below. |
-| `message` | object | The inbound message. See [Message](#message) below. |
+| `space` | `{ id, platform }` | The conversation context. See [Space](#space) below. |
+| `message` | `object` | The inbound message. See [Message](#message) below. |
 
 #### Space
 
@@ -102,7 +96,7 @@ This is the only event currently emitted. It fires once per inbound message that
 | `id` | `string` | Opaque, stable identifier for the conversation. Format varies by platform and space type — treat it as a string you store and pass back unchanged. For iMessage DMs, looks like `any;-;+<E.164>`; for groups, a chat GUID. |
 | `platform` | `string` | The platform that owns this space. See [Providers](/spectrum-ts/providers) for the current set of values; new platforms add new values without breaking existing payloads. |
 
-The `space.id` matches the `space.id` you'd see from the [`spectrum-ts` SDK](/spectrum-ts/spaces-and-users). To send a reply, pass it to <TypeTooltip name="Space" type={`{{ space.signature }}`} />`.send(...)` from a separately-running SDK instance — there is no public HTTP send-message endpoint today.
+The `space.id` matches the `space.id` you'd see from the [`spectrum-ts` SDK](/spectrum-ts/spaces-and-users) — pass it to `Space.send(...)` from a separately-running SDK instance to reply. There is no public HTTP send-message endpoint today.
 
 #### Message
 
@@ -112,8 +106,8 @@ The `space.id` matches the `space.id` you'd see from the [`spectrum-ts` SDK](/sp
 | `platform` | `string` | The platform that sourced the message. Same value as `space.platform`. |
 | `direction` | `"inbound"` | Always `"inbound"` — outbound messages are not delivered as webhooks. |
 | `timestamp` | `string` | ISO 8601 UTC timestamp from the platform (when the user sent it). |
-| `sender` | <TypeTooltip name="User" type={`{{ user.signature }}`} /> | The user who sent the message — `{ id, platform }`. The `id` format is platform-defined (e.g. for iMessage it's the E.164 phone number `+15551234567`; for WhatsApp Business it's the WA contact id). |
-| `space` | <TypeTooltip name="Space" type={`{{ space.signature }}`} /> | A copy of the top-level `space` field, denormalized for convenience. |
+| `sender` | `{ id, platform }` | The user who sent the message. The `id` format is platform-defined (for iMessage it's the E.164 phone number `+15551234567`; for WhatsApp Business it's the WA contact id). |
+| `space` | `{ id, platform }` | A copy of the top-level `space` field, denormalized for convenience. |
 | `content` | object | The message content. Shape depends on the message type — see [Content shapes](#content-shapes) below. |
 
 #### Idempotency: the `message.id` rule
diff --git a/webhooks/delivery.mdx b/webhooks/delivery.mdx
@@ -5,9 +5,15 @@ description: How Spectrum decides when to retry, when to give up, and what your
 
 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
+## The contract at a glance
 
-Spectrum tries to deliver each event for up to four attempts within a ~6.2 second window. Each attempt has a 10-second per-request timeout. Retries happen on `5xx`, `408`, `429`, network errors, and our own timeouts; other `4xx` codes mean "give up." Successful deliveries acknowledge with any `2xx`. After the budget is exhausted the event is dropped from the worker's memory — there is no durable retry queue. Customers who care about every event must dedupe and tolerate occasional misses.
+- **Strong retry behaviour.** Up to 4 attempts per event, with backoff on `5xx`, `408`, `429`, network errors, and worker-side timeouts. The vast majority of deliveries land on attempt 1; the retries are there for the occasional bad minute on your side.
+- **Fast acknowledgement.** Any `2xx` ends it — the worker stops as soon as your server says ok.
+- **Fast permanent failure.** Other `4xx` codes (`400`/`401`/`404`/etc.) are treated as fatal — we don't waste your retry budget when the request will never succeed.
+- **Bounded budget.** 10-second per-attempt timeout, ~6.2 second total across all retries. If your server is still down after that, the event is logged and the worker moves on.
+- **At-least-once delivery.** A retry after your server timed out can re-deliver an event you already processed — always dedupe in your handler (see [Be idempotent](#be-idempotent) below).
+
+This is a bounded-retry contract, not zero-loss delivery. If your use case requires *every* event regardless of downtime (financial audit, transactional state machines), pair webhooks with periodic reconciliation against the [Spectrum API](/api-reference/introduction) — covered later on this page.
 
 ## What the worker does on each attempt
 
diff --git a/webhooks/managing-webhooks.mdx b/webhooks/managing-webhooks.mdx
@@ -28,13 +28,47 @@ Project credentials are scoped to a single project. They never expire — rotate
 
 ## Register a webhook
 
-```sh
+<CodeGroup>
+```sh curl
 curl -X POST "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/" \
   -u "$PROJECT_ID:$PROJECT_SECRET" \
   -H "Content-Type: application/json" \
   -d '{"webhookUrl":"https://your-app.com/spectrum-webhook"}'
 ```
 
+```ts JavaScript
+const auth = Buffer.from(`${PROJECT_ID}:${PROJECT_SECRET}`).toString('base64');
+
+const res = await fetch(
+  `https://spectrum.photon.codes/projects/${PROJECT_ID}/webhooks/`,
+  {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${auth}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ webhookUrl: 'https://your-app.com/spectrum-webhook' }),
+  }
+);
+
+const { data } = await res.json();
+console.log('signingSecret:', data.signingSecret); // save this — only shown once
+```
+
+```py Python
+import httpx, os
+
+res = httpx.post(
+    f"https://spectrum.photon.codes/projects/{os.environ['PROJECT_ID']}/webhooks/",
+    auth=(os.environ['PROJECT_ID'], os.environ['PROJECT_SECRET']),
+    json={"webhookUrl": "https://your-app.com/spectrum-webhook"},
+)
+
+data = res.json()["data"]
+print("signingSecret:", data["signingSecret"])  # save this — only shown once
+```
+</CodeGroup>
+
 Response (`200 OK`):
 
 ```json
@@ -70,11 +104,36 @@ The `signingSecret` is **only returned in this response**. There is no `GET` end
 
 ## List registered webhooks
 
-```sh
+<CodeGroup>
+```sh curl
 curl -u "$PROJECT_ID:$PROJECT_SECRET" \
   "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
 ```
 
+```ts JavaScript
+const auth = Buffer.from(`${PROJECT_ID}:${PROJECT_SECRET}`).toString('base64');
+
+const res = await fetch(
+  `https://spectrum.photon.codes/projects/${PROJECT_ID}/webhooks/`,
+  { headers: { Authorization: `Basic ${auth}` } }
+);
+
+const { data } = await res.json();
+console.log(data); // array of { id, webhookUrl, createdAt, updatedAt }
+```
+
+```py Python
+import httpx, os
+
+res = httpx.get(
+    f"https://spectrum.photon.codes/projects/{os.environ['PROJECT_ID']}/webhooks/",
+    auth=(os.environ['PROJECT_ID'], os.environ['PROJECT_SECRET']),
+)
+
+print(res.json()["data"])  # list of { id, webhookUrl, createdAt, updatedAt }
+```
+</CodeGroup>
+
 Response:
 
 ```json
@@ -105,12 +164,32 @@ The list response **does not include `signingSecret`**. It's only ever returned
 
 ## Delete a webhook
 
-```sh
+<CodeGroup>
+```sh curl
 curl -X DELETE \
   -u "$PROJECT_ID:$PROJECT_SECRET" \
   "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b/"
 ```
 
+```ts JavaScript
+const auth = Buffer.from(`${PROJECT_ID}:${PROJECT_SECRET}`).toString('base64');
+
+await fetch(
+  `https://spectrum.photon.codes/projects/${PROJECT_ID}/webhooks/${webhookId}/`,
+  { method: 'DELETE', headers: { Authorization: `Basic ${auth}` } }
+);
+```
+
+```py Python
+import httpx, os
+
+httpx.delete(
+    f"https://spectrum.photon.codes/projects/{os.environ['PROJECT_ID']}/webhooks/{webhook_id}/",
+    auth=(os.environ['PROJECT_ID'], os.environ['PROJECT_SECRET']),
+)
+```
+</CodeGroup>
+
 Response:
 
 ```json
diff --git a/webhooks/overview.mdx b/webhooks/overview.mdx
@@ -40,15 +40,13 @@ The next six pages build on each other. Skim straight to the topic you need, or
 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>
-**Three ways to register and manage webhooks** — pick whichever fits how you work:
+## Three ways to manage webhooks
 
-- **Dashboard.** Open your workspace at [app.photon.codes/dashboard](https://app.photon.codes/dashboard) and use the **Webhook** tab to add, list, and remove endpoints with point-and-click. No terminal, no auth headers — friendly enough to hand to a non-engineer.
-- **Interactive API reference.** Every endpoint is live in the [API reference](/api-reference/introduction) — paste your project credentials once and fire `List webhooks`, `Register webhook`, or `Delete webhook` straight from your browser. Fastest way to confirm credentials work and sanity-check a URL.
-- **`curl` or any HTTP client.** The terminal flow used throughout this guide and the [Quickstart](/webhooks/quickstart). Scriptable, automatable, CI-friendly.
+You can register, list, and delete webhooks through any of three surfaces — same three operations under the hood, different ergonomics:
 
-Same three operations under the hood — just three different surfaces over them.
-</Tip>
+- **[Dashboard](https://app.photon.codes/dashboard).** Open your workspace and use the **Webhook** tab to add and remove endpoints with point-and-click. No terminal, no auth headers — the friendliest entry point, and fine to hand to a non-engineer.
+- **[Interactive API reference](/api-reference/introduction).** Every endpoint runs straight from your browser. Paste your project credentials once and fire `List webhooks`, `Register webhook`, or `Delete webhook`. Fastest way to confirm credentials work or sanity-check a URL.
+- **`curl` or any HTTP client.** The terminal flow used in the [Quickstart](/webhooks/quickstart) and the rest of this guide. Scriptable, automatable, CI-friendly.
 
 ## When to use webhooks
 
@@ -96,9 +94,7 @@ Four ideas cover everything else in these docs:
 
 ## Currently emitted events
 
-| Event | Header value | Payload shape |
-| --- | --- | --- |
-| Inbound message | `X-Spectrum-Event: messages` | `{ event, space, message }` — see [Events](/webhooks/events) |
+Today there is one event: **`messages`**. Each delivery carries `X-Spectrum-Event: messages` and a body of shape `{ event, space, message }` — see [Events](/webhooks/events) for every field.
 
 The set will grow (reactions, typing indicators, custom provider events). New event types are additive: existing handlers that ignore unknown values keep working without changes.
 
@@ -113,16 +109,10 @@ Your signing secret is returned exactly once, in the response of `POST /webhooks
 ## Where to next
 
 <Columns cols={2}>
-  <Card title="Quickstart" icon="rocket" href="/webhooks/quickstart">
-    Register a URL, verify a signature, receive your first event in 5 minutes.
+  <Card title="Start: Quickstart" icon="rocket" href="/webhooks/quickstart">
+    Wire up a URL, verify a signature, receive a real message — five minutes, end-to-end.
   </Card>
-  <Card title="Events" icon="rss" href="/webhooks/events">
-    The exact wire format — headers, body, and what each field contains.
-  </Card>
-  <Card title="Verifying signatures" icon="shield-halved" href="/webhooks/verifying-signatures">
-    The security model with complete verifier code for Node, Bun, and Python.
-  </Card>
-  <Card title="Delivery and retries" icon="repeat" href="/webhooks/delivery">
-    Retry policy, timeouts, idempotency, and what HTTP status codes mean to us.
+  <Card title="Skim: How it works" icon="diagram-project" href="#how-it-works">
+    The mechanics first, in case you'd rather build a mental model before touching code.
   </Card>
 </Columns>
diff --git a/webhooks/verifying-signatures.mdx b/webhooks/verifying-signatures.mdx
@@ -1,6 +1,6 @@
 ---
 title: Verifying signatures
-description: Confirm each delivery is genuine, unmodified, and recent — copy-paste verifier code for Node, Bun, and Python
+description: Confirm each delivery is genuine, unmodified, and recent — copy-paste verifier code for Node, Bun, Python, and Go
 ---
 
 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.
