From dafc40498626bb999ef45a6909cadd20d20d3fcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Gulbinowicz?= <pawel.gulbinowicz@supabase.io>
Date: Fri, 2 Oct 2026 15:32:17 +0200
Subject: [PATCH] docs(platform): fixes

---
 .../Navigation/NavigationMenu/NavigationMenu.constants.ts | 8 ++------
 apps/docs/content/guides/platform/webhooks.mdx            | 6 +++---
 apps/docs/content/guides/platform/webhooks/events.mdx     | 4 ++--
 3 files changed, 7 insertions(+), 11 deletions(-)

diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index 8024acc3575..a30f51335e7 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2774,12 +2774,7 @@ export const platform: NavMenuConstant = {
           name: 'Personal Access Tokens',
           url: '/guides/platform/personal-access-tokens' as `/${string}`,
           enabled: fullPlatformEnabled,
-        },
-        {
-          name: 'Platform Webhooks',
-          url: '/guides/platform/webhooks' as `/${string}`,
-          enabled: fullPlatformEnabled,
-        },
+        },        
         {
           name: 'Multi-factor Authentication',
           url: '/guides/platform/multi-factor-authentication',
@@ -2849,6 +2844,7 @@ export const platform: NavMenuConstant = {
         {
           name: 'Platform Webhooks',
           url: '/guides/platform/webhooks',
+          enabled: fullPlatformEnabled,
           items: [
             { name: 'Overview', url: '/guides/platform/webhooks' as `/${string}` },
             { name: 'Events', url: '/guides/platform/webhooks/events' as `/${string}` },
diff --git a/apps/docs/content/guides/platform/webhooks.mdx b/apps/docs/content/guides/platform/webhooks.mdx
index 10af0fd1f9a..c3b3807ec00 100644
--- a/apps/docs/content/guides/platform/webhooks.mdx
+++ b/apps/docs/content/guides/platform/webhooks.mdx
@@ -128,7 +128,7 @@ curl -X POST 'https://api.supabase.com/v2/organizations/{your-org-slug}/webhooks
         "event_types": [
           { "type": "v1.project.paused" },
           { "type": "v1.project.restored" }
-        ],
+        ]
       }
     }
   }'
@@ -151,7 +151,7 @@ curl -X POST 'https://api.supabase.com/v2/projects/{your-project-ref}/webhooks/e
         "event_types": [
           { "type": "v1.project.paused" },
           { "type": "v1.project.restored" }
-        ],
+        ]
       }
     }
   }'
@@ -306,7 +306,7 @@ Best practices for consuming webhook events and building a reliable, production-
 - Check the event type version prefix before processing a payload. For unsupported versions, return `2xx` without processing and log or alert on the unrecognized version — the transition window is finite, so upgrade your handler promptly.
 - Respond to a webhook immediately and process each event asynchronously, for example, on a job queue.
 - Keep track of already processed events in persistent storage to deduplicate them, for example, in a database.
-- Keep track of the last processed event's timestamp and discard stale events. Do not rely on the order of events.
+- Keep track of the last processed event's timestamp and discard stale events of the same type. Do not rely on the order of events.
 - Treat webhook events as a trigger for an action, rather than the state of a resource.
 - Use the webhook's automatic retries as a safeguard against network partitions or timeouts, not as a fallback for listener logic errors.
 - Periodically check delivery history for permanently failed deliveries. Supabase does not notify you when all retries are exhausted.
diff --git a/apps/docs/content/guides/platform/webhooks/events.mdx b/apps/docs/content/guides/platform/webhooks/events.mdx
index 0c3ebaa6579..cb85d98c21f 100644
--- a/apps/docs/content/guides/platform/webhooks/events.mdx
+++ b/apps/docs/content/guides/platform/webhooks/events.mdx
@@ -49,7 +49,7 @@ For example:
 }
 ```
 
-Organization scoped events always have `project_ref` set to `null`, since they do not relate to any project in particular.
+Organization scoped events always have `project_ref` set to `null` because they do not relate to a specific project.
 
 The version prefix in the `type` field, such as `v1`, identifies the payload schema. For how versions change over time and how to handle an unrecognized version, see [Versioning](/docs/guides/platform/webhooks#versioning).
 
@@ -77,7 +77,7 @@ Present only on test events sent through the [Send a test event](/docs/guides/pl
 
 Project events fire when a change occurs or an action is taken in a specific project. The payload always includes both non-nullable `organization_slug` and `project_ref`.
 
-| Event                                                  | Fires after                                      |
+| Event                                                  | Fires when                                      |
 | ------------------------------------------------------ | ------------------------------------------------ |
 | [`v1.project.created`](#v1projectcreated)              | A project is created                             |
 | [`v1.project.paused`](#v1projectpaused)                | A project is paused                              |