mirror of
https://github.com/supabase/supabase.git
synced 2026-10-08 02:45:07 +03:00
6ecf98671a
## Problem Platform Webhooks (org- and project-level event notifications over the Management API) has no public documentation. CTRL-1017 asks for a docs page plus a specification of the available event types, so partners can integrate without reading the OpenAPI spec or asking engineering directly. Closes CTRL-1017. ## Solution **New guide covering the Management API path, plus an event catalog.** Adds `apps/docs/content/guides/platform/webhooks.mdx`: concepts and scoping, creating an endpoint, Standard Webhooks signature verification and secret rotation, test events, and delivery/retry/ordering behavior. Adds `apps/docs/content/guides/platform/webhooks/events.mdx`: the events reference. - Full payload documentation for the 8 project-lifecycle event types, and a name-and-trigger table for the 12 branch, member, and billing types whose payload fields aren't documented. - Documents `*` for subscribing to every event. - Access framing states the criterion: available to organizations on an early access allowlist, with the `403` / `access_disabled` response for everyone else. - Nav entry under Platform > Project & Account Management, after Personal Access Tokens, gated by `fullPlatformEnabled`. **The page deliberately omits the dashboard UI.** See the first row of the table below. ## Needs review before merge | Item | Detail | | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **The Studio webhooks UI is not wired to the API, so this page documents the Management API only** | `PlatformWebhooksPage.tsx:29` imports `PLATFORM_WEBHOOKS_MOCK_DATA`; `PlatformWebhooks.store.ts` has no async or network code and hardcodes `createdBy: 'mock-user@supabase.io'`; nothing in `apps/studio` references `webhooks/endpoints` or `webhooks/deliveries`, even though `api-types/types/api-v2.d.ts` carries those paths 24 times. #43276 (DEPR-340) described it as "UI-only (with mock data)", and the `DEPR-340-backend-integration-tracker.md` it pointed to is no longer in the tree. A dashboard section can be added once the UI calls the API. | | Possible reference slug collision | Project- and org-scoped operations share identical `summary` values (both "Create endpoint", both "List endpoints"). The page links to the reference introduction and names the **Project webhooks** / **Organization webhooks** tags rather than deep-linking a generated page. | ## Preview links **Verified:** the new page returns 200 on the preview; the same path returns 404 on production, confirming net-new content; the nav entry renders on the preview build. ### Proof: new page renders on the PR preview [Open the new page on preview](https://docs-git-nikrichers-ctrl-1017-set-up-public-doc-fa3960-supabase.vercel.app/docs/guides/platform/webhooks) <img width="2295" height="8039" alt="Screenshot 2026-10-05 at 11-47-06 Platform Webhooks Supabase Docs" src="https://github.com/user-attachments/assets/7b1440d3-207d-4828-8593-77140bdcd73f" /> <img width="2295" height="12000" alt="Screenshot 2026-10-05 at 11-48-49 Platform Webhook Events Supabase Docs" src="https://github.com/user-attachments/assets/2808a88e-558e-4f73-a12a-01382cd3f6a2" /> ## Review instructions 1. Open the [PR preview](https://docs-git-nikrichers-ctrl-1017-set-up-public-doc-fa3960-supabase.vercel.app/docs/guides/platform/webhooks) and confirm the page renders as shown. 2. Confirm **Platform Webhooks** appears under **Platform > Project & Account Management** in the sidebar, after **Personal Access Tokens**. 3. Confirm the five internal-guide values in the second row of the needs-review table. 4. Decide with the Control Plane team whether the Studio UI ships wired to the API, which determines when a dashboard section gets added: Studio UI is slated for Q4, so it will not be shipped together. ## Checklist Check all before review: - [x] I have read [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) - [x] If I wrote a new docs topic or edited an existing topic, I used the `/write-the-docs` or `/edit-the-docs` skill, which applies the docs [style guide](https://github.com/supabase/supabase/tree/master/apps/docs/style-guide) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a Platform Webhooks guide covering endpoint setup, event delivery, signature verification, test events, retries, retention, idempotency, ordering, and listener best practices. * Documented project and organization event types, payload schemas, event scopes, and versioning, plus access restrictions for organizations outside the allowlist. * **Navigation** * Added Platform Webhooks links, including Overview and Events, to the platform navigation when the full platform is enabled. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai> Co-authored-by: Paweł Gulbinowicz <pawel.gulbinowicz@supabase.io> Co-authored-by: Paweł Gulbinowicz <zamotany@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>