FCE-3559: Document webhook signature verification

docs/api/reference.md

@@ -32,13 +32,14 @@ The notifications can be configured using Webhook or Websocket.
 
 #### Webhook
 
-When using webhooks for receiving notifications, the `webhookUrl` must be passed
-in the `RoomConfig` options when creating a room.
+When using webhooks for receiving notifications, configure your webhook URL in
+the **Webhooks** tab of the [Fishjam Dashboard](https://fishjam.io/app).
+Fishjam then delivers all notifications to that URL.
 
-The HTTP POST to the `webhookUrl` uses "application/x-protobuf" content type.
+The HTTP POST to your webhook URL uses "application/x-protobuf" content type.
 The body is binary data, that represents encoded `ServerMessage`.
 
-Setting `batchWebhookNotifications` to `true` in the `RoomConfig` is recommended. Fishjam then coalesces several notifications into one POST: the body is still a single `ServerMessage`, but its `notification_batch` field holds a `NotificationBatch`, which carries the individual notifications as a repeated list of `ServerMessage`s (see `server_notifications.proto`). This delivers notifications faster and with fewer requests. The SDK decoders (`decodeServerNotifications` / `decode_server_notifications`) unwrap the batch for you, returning the notifications as a flat list — so a single notification and a batch are handled the same way.
+Setting `batchWebhookNotifications` to `true` in the `RoomConfig` is recommended. Fishjam then coalesces several notifications into one POST: the body is still a single `ServerMessage`, but its `notification_batch` field holds a `NotificationBatch`, which carries the individual notifications as a repeated list of `ServerMessage`s (see `server_notifications.proto`). This delivers notifications faster and with fewer requests. The SDK decoders unwrap the batch for you.
 
 For more information see also [server setup documentation](../how-to/backend/server-setup#webhooks)
 

docs/how-to/backend/fastapi-example.mdx

@@ -38,28 +38,29 @@ async def get_rooms(fishjam_client: Annotated[FishjamClient, Depends(fishjam_cli
 
 ## Listening to events
 
-Fishjam instance is a stateful server that is emitting messages upon certain events.
-You can listen for those messages and react as you prefer.
-There are two options for obtaining these.
+Fishjam emits messages upon certain events — see [Listening to events](../../how-to/backend/server-setup#listening-to-events) for how delivery, batching, and signing work.
 
 ### Webhooks
 
-To receive and parse Fishjam protobuf messages, create a dependency function that decodes the request body using the `decode_server_notifications` function from the `fishjam` package.
-It returns a list of notifications and transparently unwraps batched payloads (rooms created with `batch_webhook_notifications=True`), so you can iterate over the result and use pattern matching to respond to different kinds of events.
+Create a dependency function that [verifies the webhook signature](../../how-to/backend/server-setup#verifying-webhook-signatures) and decodes the request body into notifications, then use pattern matching to respond to different kinds of events.
 
 :::note
-`decode_server_notifications` replaces the now-deprecated `receive_binary`. It always returns a list — a single notification comes back as a one-element list — which lets the same handler work whether or not batching is enabled.
+`decode_server_notifications` replaces the now-deprecated `receive_binary`.
 :::
 
 ```python
-from fastapi import Depends, FastAPI, Request
-from fishjam import decode_server_notifications
+import os
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fishjam import decode_server_notifications, verify_webhook_signature
 from fishjam.events import ServerMessagePeerAdded
 
 app = FastAPI()
 
 async def parse_fishjam_notifications(request: Request):
     binary = await request.body()
+    signature = request.headers.get("x-fishjam-signature-256", "")
+    if not verify_webhook_signature(binary, signature, os.environ["FISHJAM_WEBHOOK_SECRET"]):
+        raise HTTPException(status_code=401, detail="Invalid webhook signature")
     return decode_server_notifications(binary)
 
 @app.post("/fishjam-webhook")

docs/how-to/backend/fastify-example.mdx

@@ -111,20 +111,18 @@ fastify.listen({ port: 3000 });
 
 ## Listening to events
 
-Fishjam instance is a stateful server that is emitting messages upon certain events.
-You can listen for those messages and react as you prefer.
-There are two options to obtain these.
+Fishjam emits messages upon certain events — see [Listening to events](../../how-to/backend/server-setup#listening-to-events) for how delivery, batching, and signing work.
 
 ### Webhooks
 
-To receive and parse the Fishjam protobuf messages, add a content type parser to your global (or scoped) Fastify instance.
-Use `decodeServerNotifications` to decode the request body: it returns a list of typed notifications and transparently unwraps a [batch](../../how-to/backend/server-setup#webhooks), so rooms created with `batchWebhookNotifications: true` are handled the same as single notifications — a single notification simply arrives as a one-element list.
-Then, you will be able to iterate over the parsed notifications at `request.body`.
+Add a content type parser to your global (or scoped) Fastify instance that [verifies the webhook signature](../../how-to/backend/server-setup#verifying-webhook-signatures) and decodes the body into typed notifications.
+You can then iterate over the parsed notifications at `request.body`.
 
 ```ts title='main.ts'
 import Fastify, { FastifyRequest } from "fastify";
 import {
   decodeServerNotifications,
+  verifyWebhookSignature,
   ServerNotification,
 } from "@fishjam-cloud/js-server-sdk";
 
@@ -133,7 +131,22 @@ const fastify = Fastify();
 fastify.addContentTypeParser(
   "application/x-protobuf",
   { parseAs: "buffer" },
-  async (_: FastifyRequest, body: Buffer) => decodeServerNotifications(body),
+  async (request: FastifyRequest, body: Buffer) => {
+    const signature = request.headers["x-fishjam-signature-256"];
+    if (
+      typeof signature !== "string" ||
+      !verifyWebhookSignature(
+        body,
+        signature,
+        process.env.FISHJAM_WEBHOOK_SECRET!,
+      )
+    ) {
+      throw Object.assign(new Error("Invalid webhook signature"), {
+        statusCode: 401,
+      });
+    }
+    return decodeServerNotifications(body);
+  },
 );
 
 fastify.post<{ Body: ServerNotification[] }>("/fishjam-webhook", (request) => {

docs/how-to/backend/production-deployment.mdx

@@ -226,14 +226,17 @@ All you need for this is a single api endpoint:
 
 ### Webhook endpoint
 
-Fishjam delivers notifications as a binary `application/x-protobuf` body. Read the raw body and decode it with the SDK, then react to the events you care about.
+Fishjam delivers notifications as a binary `application/x-protobuf` body. Read the raw body, [verify the webhook signature](../../how-to/backend/server-setup#verifying-webhook-signatures), and decode it with the SDK, then react to the events you care about. Store your webhook secret as `FISHJAM_WEBHOOK_SECRET`.
 
 <Tabs groupId="language">
   <TabItem value="ts" label="Node.js / TypeScript">
 
     ```typescript
     import express from "express";
-    import { decodeServerNotifications } from "@fishjam-cloud/js-server-sdk";
+    import {
+      decodeServerNotifications,
+      verifyWebhookSignature,
+    } from "@fishjam-cloud/js-server-sdk";
 
     const app = express();
     const handlePeerConnected = {} as any;
@@ -245,6 +248,18 @@ Fishjam delivers notifications as a binary `application/x-protobuf` body. Read t
       "/api/webhooks/fishjam",
       express.raw({ type: "application/x-protobuf" }),
       (req: express.Request, res: express.Response) => {
+        const signature = req.headers["x-fishjam-signature-256"];
+        if (
+          typeof signature !== "string" ||
+          !verifyWebhookSignature(
+            req.body,
+            signature,
+            process.env.FISHJAM_WEBHOOK_SECRET!,
+          )
+        ) {
+          return res.status(401).json({ error: "Invalid signature" });
+        }
+
         for (const { type, notification } of decodeServerNotifications(req.body)) {
           switch (type) {
             case "peerConnected":
@@ -271,8 +286,9 @@ Fishjam delivers notifications as a binary `application/x-protobuf` body. Read t
   <TabItem value="python" label="Python">
 
     ```python
-    from fastapi import FastAPI, Request
-    from fishjam import decode_server_notifications
+    import os
+    from fastapi import FastAPI, HTTPException, Request
+    from fishjam import decode_server_notifications, verify_webhook_signature
     from fishjam.events import (
         ServerMessagePeerConnected,
         ServerMessagePeerDisconnected,
@@ -283,7 +299,12 @@ Fishjam delivers notifications as a binary `application/x-protobuf` body. Read t
 
     @app.post("/api/webhooks/fishjam")
     async def fishjam_webhook(request: Request):
-        for notification in decode_server_notifications(await request.body()):
+        raw_body = await request.body()
+        signature = request.headers.get("x-fishjam-signature-256", "")
+        if not verify_webhook_signature(raw_body, signature, os.environ["FISHJAM_WEBHOOK_SECRET"]):
+            raise HTTPException(status_code=401, detail="Invalid signature")
+
+        for notification in decode_server_notifications(raw_body):
             match notification:
                 case ServerMessagePeerConnected():
                     handle_peer_connected(notification)
@@ -301,7 +322,7 @@ Fishjam delivers notifications as a binary `application/x-protobuf` body. Read t
 
 ### Enabling webhooks
 
-Now, with your endpoint setup, all you need to do is supply your webhook endpoint to Fishjam when creating a room. We also recommend enabling `batchWebhookNotifications`, which delivers notifications faster and with fewer HTTP requests for a better backend response time under load:
+Now, with your endpoint set up, register its URL in the **Webhooks** tab of the [Fishjam Dashboard](https://fishjam.io/app). Fishjam then delivers all notifications to that endpoint. We also recommend enabling [notification batching](../../how-to/backend/server-setup#webhooks) when creating rooms:
 
 <Tabs groupId="language">
   <TabItem value="ts" label="Node.js / TypeScript">
@@ -311,10 +332,9 @@ Now, with your endpoint setup, all you need to do is supply your webhook endpoin
     const fishjamClient = {} as any;
 
     // ---cut---
-    const createRoomWithWebhooks = async (roomType = "conference") => {
+    const createBatchedRoom = async (roomType = "conference") => {
       const room = await fishjamClient.createRoom({
         roomType,
-        webhookUrl: `${process.env.BASE_URL}/api/webhooks/fishjam`,
         // Coalesce notifications into batches for faster delivery and fewer requests
         batchWebhookNotifications: true,
       });
@@ -336,10 +356,9 @@ Now, with your endpoint setup, all you need to do is supply your webhook endpoin
         management_token=os.environ["FISHJAM_MANAGEMENT_TOKEN"],
     )
 
-    def create_room_with_webhooks(room_type="conference"):
+    def create_batched_room(room_type="conference"):
         options = RoomOptions(
             room_type=room_type,
-            webhook_url=f"{os.environ['BASE_URL']}/api/webhooks/fishjam",
             # Coalesce notifications into batches for faster delivery and fewer requests
             batch_webhook_notifications=True,
         )

docs/how-to/backend/server-setup.mdx

@@ -226,9 +226,9 @@ There are two options to obtain these.
 
 ### Webhooks
 
-Simply pass your webhook URL as a `webhookUrl` parameter when creating a room.
+Configure your webhook URL in the **Webhooks** tab of the [Fishjam Dashboard](https://fishjam.io/app). Fishjam then delivers all notifications to that URL.
 
-We recommend also enabling **notification batching** via `batchWebhookNotifications`. Fishjam then coalesces several notifications into a single request, delivering them faster and with fewer HTTP requests — which improves your backend's response time under load.
+We recommend also enabling **notification batching** when creating a room. Fishjam then coalesces several notifications into a single request, delivering them faster and with fewer HTTP requests — which improves your backend's response time under load.
 
 <Tabs groupId="language">
   <TabItem value="ts" label="Typescript">
@@ -241,8 +241,7 @@ We recommend also enabling **notification batching** via `batchWebhookNotificati
         managementToken: "bbb",
     });
     // ---cut---
-    const webhookUrl = "https://example.com/";
-    await fishjamClient.createRoom({ webhookUrl, batchWebhookNotifications: true });
+    await fishjamClient.createRoom({ batchWebhookNotifications: true });
     ```
 
   </TabItem>
@@ -253,7 +252,6 @@ We recommend also enabling **notification batching** via `batchWebhookNotificati
     from fishjam import RoomOptions
 
     options = RoomOptions(
-        webhook_url="https://example.com/",
         batch_webhook_notifications=True,
     )
 
@@ -264,7 +262,7 @@ We recommend also enabling **notification batching** via `batchWebhookNotificati
 
 </Tabs>
 
-On the receiving side, decode the raw request body with `decodeServerNotifications` (Node) or `decode_server_notifications` (Python), then iterate the result and react to the events you care about. Both decoders return a list of notifications and transparently unwrap a batch — a single notification simply comes back as a one-element list, so the same handler works whether or not batching is enabled.
+On the receiving side, decode the raw request body with the SDK's decoder, then iterate the result and react to the events you care about. The decoder returns a list of notifications and transparently unwraps a batch — a single notification simply comes back as a one-element list, so the same handler works whether or not batching is enabled.
 
 <Tabs groupId="language">
   <TabItem value="ts" label="Typescript">
@@ -319,6 +317,56 @@ On the receiving side, decode the raw request body with `decodeServerNotificatio
 
 </Tabs>
 
+#### Verifying webhook signatures
+
+Every webhook request is signed so you can confirm it really came from Fishjam. Each delivery carries an `x-fishjam-signature-256: sha256=<hex>` header — an HMAC-SHA256 of the **raw request body**, keyed with your webhook secret. Find (and rotate) that secret in the **Webhooks** tab of the [Fishjam Dashboard](https://fishjam.io/app).
+
+Verify the header against the raw body **before** decoding, and reject mismatches with `401`. Verification needs the exact bytes Fishjam sent, so read the raw body before any parsing.
+
+<Tabs groupId="language">
+  <TabItem value="ts" label="Typescript">
+
+    ```ts
+    declare const rawBody: Buffer;
+    declare const signatureHeader: string;
+    // ---cut---
+    import { verifyWebhookSignature, decodeServerNotifications } from '@fishjam-cloud/js-server-sdk';
+
+    const secret = process.env.FISHJAM_WEBHOOK_SECRET!;
+
+    // rawBody: Buffer, signatureHeader: req.headers['x-fishjam-signature-256']
+    if (!verifyWebhookSignature(rawBody, signatureHeader, secret)) {
+      // respond with 401 here — how depends on your framework, see the examples linked below
+      throw new Error('Invalid webhook signature');
+    }
+
+    // signature is valid — safe to decode
+    const notifications = decodeServerNotifications(rawBody);
+    ```
+
+  </TabItem>
+
+  <TabItem value="python" label="Python">
+
+    ```python
+    import os
+    from fishjam import verify_webhook_signature, decode_server_notifications
+
+    secret = os.environ["FISHJAM_WEBHOOK_SECRET"]
+
+    # raw_body: bytes, signature_header: request.headers["x-fishjam-signature-256"]
+    if not verify_webhook_signature(raw_body, signature_header, secret):
+        # respond with 401 here — how depends on your framework, see the examples linked below
+        raise PermissionError("Invalid webhook signature")
+
+    # signature is valid — safe to decode
+    notifications = decode_server_notifications(raw_body)
+    ```
+
+  </TabItem>
+
+</Tabs>
+
 See the [Fastify](../../how-to/backend/fastify-example#webhooks) and [FastAPI](../../how-to/backend/fastapi-example#webhooks) examples for a full webhook handler wired into a web framework.
 
 ### SDK Notifier

docs/tutorials/backend-quick-start.mdx

@@ -562,7 +562,7 @@ Here's a complete working backend:
 Now that you have a working backend, explore these guides:
 
 - [How to set up a production deployment](../how-to/backend/production-deployment)
-- [How to handle webhooks and events](../how-to/backend/server-setup)
+- [How to handle webhooks and events](../how-to/backend/server-setup#webhooks)
 - [How to implement a FastAPI backend](../how-to/backend/fastapi-example)
 - [How to implement a Fastify backend](../how-to/backend/fastify-example)