Merge pull request #25 from photon-hq/fix-webhooks-docs

fix: fix webhook docs for semantics and accuracy

Author: yanxue06

api-reference/endpoint/webhook.mdx

@@ -20,21 +20,21 @@ X-Spectrum-Signature: v0=3a1f7c8b2d9e0a4f6e3c5b8a1d2e4f6a8b0c3d5e7f9a1b2c4d6e8f0
 {
   "event": "messages",
   "space": {
-    "id": "imessage:chat:42",
-    "platform": "imessage"
+    "id": "any;-;+15550100",
+    "platform": "iMessage"
   },
   "message": {
-    "id": "imessage:msg:abc123",
-    "platform": "imessage",
+    "id": "spc-msg-00000000-0000-4000-8000-000000000001",
+    "platform": "iMessage",
     "direction": "inbound",
     "timestamp": "2026-05-14T19:06:32.000Z",
     "sender": {
-      "id": "imessage:+15551234567",
-      "platform": "imessage"
+      "id": "+15550100",
+      "platform": "iMessage"
     },
     "space": {
-      "id": "imessage:chat:42",
-      "platform": "imessage"
+      "id": "any;-;+15550100",
+      "platform": "iMessage"
     },
     "content": {
       "type": "text",
@@ -83,10 +83,10 @@ This is the only event currently emitted. It fires once per inbound message that
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `string` | Stable, platform-prefixed identifier (e.g. `imessage:chat:42`). |
-| `platform` | `string` | The platform that owns this space (`imessage`, `whatsapp_business`). |
+| `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). You can use it to send a reply back via the [Spectrum API](/api-reference/introduction).
+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 `space.send(...)` from a separately-running SDK instance — there is no public HTTP send-message endpoint today.
 
 #### Message
 
@@ -100,6 +100,25 @@ The `space.id` matches the `space.id` you'd see from the [`spectrum-ts` SDK](/sp
 | `space` | object | A copy of the top-level `space` field, denormalized for convenience. |
 | `content` | object | The message content. Shape depends on the message type — see below. |
 
+#### Idempotency: the `message.id` rule
+
+A single inbound message **always carries the same `message.id` across every delivery it produces**, no matter how many webhook URLs you have registered. If you have two URLs registered for one project and a message arrives, both URLs receive a `POST` in parallel — and both bodies have the same `message.id`. If a delivery is retried (after a 5xx or timeout on your side), the retry also carries the same `message.id`.
+
+That makes `message.id` the right dedup key when one downstream consumer handles every webhook for the project:
+
+```ts
+const dedupeKey = payload.message.id;
+if (await store.exists(dedupeKey)) return new Response('ok', { status: 200 });
+await processOnce(payload);
+await store.set(dedupeKey, true, { ttl: 48 * 60 * 60 });
+```
+
+If different services consume different webhook URLs and each one needs its own dedup table, scope the key with the webhook id so the same message processed by service A doesn't suppress service B:
+
+```ts
+const dedupeKey = `${webhookId}:${payload.message.id}`;
+```
+
 #### Content shapes
 
 `content` is a discriminated union tagged by `type`. It mirrors the [`message.content` shape](/spectrum-ts/content) from the `spectrum-ts` SDK.
@@ -122,7 +141,7 @@ Always handle unknown `content.type` values gracefully — new content types may
 
 A few things that may be in the SDK's `Message` type but are intentionally **not** in the webhook payload:
 
-- **Methods like `.reply()` or `.react()`.** They depend on a live SDK connection. To respond, call the [Spectrum API](/api-reference/introduction) using `space.id`.
+- **Methods like `.reply()` or `.react()`.** They depend on a live SDK connection. To respond, run [`spectrum-ts`](/spectrum-ts/getting-started) in a separate process and call `space.send(...)` against the `space.id` you got from the webhook. There is no HTTP send endpoint yet.
 - **Internal provider state.** Things like raw protocol headers, retry hints, and message acknowledgements are stripped before serialization.
 - **Outbound messages.** Webhooks deliver inbound only. A message you sent does not echo back as a webhook.
 

webhooks/events.mdx

@@ -7,24 +7,25 @@ You manage webhooks through three HTTP endpoints on the Spectrum API. All requir
 
 ## Authentication
 
-Every request uses HTTP Basic auth where the username is your `projectId` and the password is your `projectSecret`.
+Every request uses HTTP Basic auth where the username is your `projectId` and the password is your `projectSecret`. The `projectId` also appears in the URL path — both are required.
 
 ```sh
-curl -u "$PROJECT_ID:$PROJECT_SECRET" https://spectrum.photon.codes/webhooks/
+curl -u "$PROJECT_ID:$PROJECT_SECRET" \
+  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
 ```
 
 Project credentials are scoped to a single project. They never expire — rotate them via `photon projects regenerate-secret <id>` (see the [CLI projects docs](/cli/projects#rotate-the-spectrum-api-secret)) if they leak.
 
 ## Register a webhook
 
 ```sh
-curl -X POST https://spectrum.photon.codes/webhooks/ \
+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"}'
 ```
 
-Response (`201 Created`):
+Response (`200 OK`):
 
 ```json
 {
@@ -47,21 +48,21 @@ The `signingSecret` is **only returned in this response**. There is no `GET` end
 
 | Status | When it happens | What to do |
 | --- | --- | --- |
-| `400` | Invalid `webhookUrl` (not HTTPS, malformed) | Use a valid `https://` URL |
+| `422` | `webhookUrl` fails schema validation (empty, malformed, etc.) | Send a syntactically valid URL string |
 | `409` | The same URL is already registered for this project | List existing webhooks, or delete the old one and re-register |
 | `401` | Bad project credentials | Rotate via the CLI and try again |
 
 ### URL requirements
 
-- Must be `https://`.
-- Must be reachable from the public internet — this isn't strict, but if Spectrum can't reach it, every delivery fails.
+- Should be `https://`. We accept `http://` URLs today and don't reject them at registration, but delivery is then sent in plaintext — anyone on the network path can read the payload and forge requests. Treat HTTPS as a hard requirement for any non-toy webhook.
+- Must be reachable from the public internet — if Spectrum can't reach it, every delivery fails after the retry budget exhausts.
 - Path component is yours to choose; we POST to it as-is.
 
 ## List registered webhooks
 
 ```sh
 curl -u "$PROJECT_ID:$PROJECT_SECRET" \
-  https://spectrum.photon.codes/webhooks/
+  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
 ```
 
 Response:
@@ -97,7 +98,7 @@ The list response **does not include `signingSecret`**. It's only ever returned
 ```sh
 curl -X DELETE \
   -u "$PROJECT_ID:$PROJECT_SECRET" \
-  https://spectrum.photon.codes/webhooks/6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b
+  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b/"
 ```
 
 Response:
@@ -125,7 +126,7 @@ There is no dedicated rotation endpoint. To rotate, **delete and re-register**:
 OLD_ID=6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b
 
 # 2. Register the same URL — get a new secret
-curl -X POST https://spectrum.photon.codes/webhooks/ \
+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"}'
@@ -135,7 +136,7 @@ curl -X POST https://spectrum.photon.codes/webhooks/ \
 
 # 4. Delete the old webhook
 curl -X DELETE -u "$PROJECT_ID:$PROJECT_SECRET" \
-  https://spectrum.photon.codes/webhooks/$OLD_ID
+  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/$OLD_ID/"
 ```
 
 <Tip>
@@ -176,8 +177,11 @@ A first-class `photon webhooks` CLI is on the roadmap. Until then, wrap the curl
 ```sh
 # A small helper to list webhooks for the active project
 list_webhooks() {
-  local creds=$(photon projects show --json | jq -r '"\(.id):\(.secret)"')
-  curl -s -u "$creds" https://spectrum.photon.codes/webhooks/
+  local row creds id
+  row=$(photon projects show --json)
+  id=$(echo "$row" | jq -r '.id')
+  creds=$(echo "$row" | jq -r '"\(.id):\(.secret)"')
+  curl -s -u "$creds" "https://spectrum.photon.codes/projects/$id/webhooks/"
 }
 ```
 

webhooks/managing-webhooks.mdx

@@ -1,6 +1,6 @@
 ---
 title: Webhooks
-description: Receive iMessage and WhatsApp events at your own URL — Spectrum signs each delivery so you know it's real
+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`.
@@ -21,7 +21,7 @@ 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 iMessage and WhatsApp Business, batching, reconnects, and signing.
+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.
 
 ## When to use webhooks
 
@@ -47,7 +47,7 @@ flowchart LR
   Retry --> URL2
 ```
 
-When a message arrives on iMessage or WhatsApp Business for a project that has webhooks registered:
+When a message arrives on any enabled platform for a project that has webhooks registered:
 
 1. Our worker receives the message from the platform.
 2. It serializes the event to JSON.

webhooks/overview.mdx

@@ -9,7 +9,7 @@ If you already have a deployed HTTPS URL, skip the ngrok step.
 
 ## Prerequisites
 
-- A Spectrum project with at least one platform enabled (iMessage or WhatsApp Business). If you don't have one yet, see [Getting Started with Spectrum](/spectrum-ts/getting-started).
+- A Spectrum project with at least one platform enabled. See [Providers](/spectrum-ts/providers) for the current list, or [Getting Started with Spectrum](/spectrum-ts/getting-started) if you don't have a project yet.
 - Your project id and project secret, from the [dashboard](https://app.photon.codes) or `photon projects show`.
 - A reachable HTTPS URL — ngrok works for local development.
 
@@ -51,7 +51,7 @@ If you already have a deployed HTTPS URL, skip the ngrok step.
   Use `curl` (or any HTTP client) to register the URL with your project credentials:
 
   ```sh
-  curl -X POST https://spectrum.photon.codes/webhooks/ \
+  curl -X POST "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/" \
     -u "$PROJECT_ID:$PROJECT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"webhookUrl":"https://abcd1234.ngrok-free.app/spectrum-webhook"}'
@@ -144,10 +144,10 @@ If you already have a deployed HTTPS URL, skip the ngrok step.
 
   <Step title="Send a real message">
 
-  From your phone, send an iMessage (or WhatsApp message) to the number attached to your project. Within a second or two, your terminal should print:
+  Send a real message to your project from any of its enabled platforms — an iMessage to the assigned number, a WhatsApp message, whatever you've configured. Within a second or two, your terminal should print:
 
   ```text
-  message from imessage:+15551234567 : { type: 'text', text: 'hi' }
+  message from +15550100 : { type: 'text', text: 'hi' }
   ```
 
   If you see `bad signature`, double-check that you exported `SPECTRUM_SIGNING_SECRET` correctly and re-started the server.
@@ -157,22 +157,42 @@ If you already have a deployed HTTPS URL, skip the ngrok step.
 
   <Step title="Reply from your handler (optional)">
 
-  The webhook delivery only carries the inbound message. To reply, call the [Spectrum API](/api-reference/introduction) (or run a separate `Spectrum()` instance for sending). A typical pattern:
+  The webhook delivery only carries inbound messages — there is no public HTTP "send a message" endpoint today. To reply, run the [`spectrum-ts`](/spectrum-ts/getting-started) SDK in a separate process (or alongside your handler) and call `space.send(...)` there. The webhook tells your service *what* arrived; the SDK is what puts a message back on the wire.
+
+  A common split:
 
   ```ts
-  if (event === 'messages' && payload.message.content.type === 'text') {
-    await fetch(`https://spectrum.photon.codes/spaces/${payload.space.id}/messages`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Basic ${btoa(`${process.env.PROJECT_ID}:${process.env.PROJECT_SECRET}`)}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ content: { type: 'text', text: 'hi back' } }),
-    });
-  }
+  // sender.ts — long-lived process holding an outbound SDK instance
+  import { Spectrum, text } from "spectrum-ts";
+  import { imessage } from "spectrum-ts/providers/imessage";
+
+  const app = await Spectrum({
+    projectId: process.env.PROJECT_ID!,
+    projectSecret: process.env.PROJECT_SECRET!,
+    providers: [imessage.config()],
+  });
+
+  // call this from your webhook handler (e.g. via a queue / RPC)
+  export const reply = async (spaceId: string, body: string) => {
+    const space = await app.spaces.get(spaceId);
+    await space.send(text(body));
+  };
+  ```
+
+  Inside the webhook handler, acknowledge with `2xx` first (the worker treats a slow response as a timeout and retries) and enqueue the reply job:
+
+  ```ts
+  app.post('/spectrum-webhook', async (c) => {
+    if (!verify(c)) return c.text('bad signature', 401);
+    const payload = JSON.parse(await c.req.text());
+    if (payload.event === 'messages' && payload.message.content.type === 'text') {
+      void enqueueReply(payload.space.id, `echo: ${payload.message.content.text}`);
+    }
+    return c.text('ok', 200);
+  });
   ```
 
-  Acknowledge the webhook (`return c.text('ok', 200)`) **before** the reply call if your reply might take >1s — the worker treats a slow response as a timeout and retries.
+  An HTTP send-message API is on the roadmap; until then, the SDK is the supported path.
   </Step>
 </Steps>
 
@@ -181,7 +201,7 @@ If you already have a deployed HTTPS URL, skip the ngrok step.
 You have an end-to-end pipeline:
 
 ```text
-phone → iMessage → Spectrum → POST /spectrum-webhook → your code
+user's device → platform → Spectrum → POST /spectrum-webhook → your code
 ```
 
 You verified each delivery is genuine (not spoofed), recent (not a replay), and unmodified (not tampered with).

webhooks/quickstart.mdx

@@ -57,7 +57,8 @@ Walk through this checklist in order:
 <Steps>
   <Step title="Confirm the webhook is registered">
   ```sh
-  curl -u "$PROJECT_ID:$PROJECT_SECRET" https://spectrum.photon.codes/webhooks/
+  curl -u "$PROJECT_ID:$PROJECT_SECRET" \
+    "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
   ```
 
   The URL you expect should appear in the list. If not, register it.
@@ -76,7 +77,7 @@ Walk through this checklist in order:
   photon spectrum platforms ls
   ```
 
-  An iMessage line that's not paired or a WhatsApp Business token that's expired produces zero inbound events. Webhooks deliver what the SDK receives — if the SDK is silent, webhooks are silent.
+  A platform that's enabled in the dashboard but not actually connected — an unpaired iMessage line, an expired WhatsApp token, a custom provider whose lifecycle handler is throwing — produces zero inbound events. Webhooks deliver what the SDK receives, so if the SDK is silent for a platform, that platform's webhooks are silent too. Check the SDK side first.
   </Step>
 
   <Step title="Confirm the message is actually inbound to your project">
@@ -153,7 +154,7 @@ Free ngrok tunnels get a new URL every restart. That URL won't be registered wit
   ```sh
   ngrok http 3000
   # Copy the new URL, then:
-  curl -X POST https://spectrum.photon.codes/webhooks/ \
+  curl -X POST "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/" \
     -u "$PROJECT_ID:$PROJECT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"webhookUrl":"https://NEW-URL.ngrok-free.app/spectrum-webhook"}'
@@ -182,14 +183,14 @@ import { createHmac } from 'node:crypto';
 const secret = 'a3f8e29b...5c7e9b2d';
 const body = JSON.stringify({
   event: 'messages',
-  space: { id: 'imessage:chat:1', platform: 'imessage' },
+  space: { id: 'any;-;+15550100', platform: 'iMessage' },
   message: {
-    id: 'imessage:msg:test1',
-    platform: 'imessage',
+    id: 'spc-msg-00000000-0000-4000-8000-000000000001',
+    platform: 'iMessage',
     direction: 'inbound',
     timestamp: new Date().toISOString(),
-    sender: { id: 'imessage:+15551234567', platform: 'imessage' },
-    space: { id: 'imessage:chat:1', platform: 'imessage' },
+    sender: { id: '+15550100', platform: 'iMessage' },
+    space: { id: 'any;-;+15550100', platform: 'iMessage' },
     content: { type: 'text', text: 'hi' },
   },
 });