feat(docs): guide for new webhooks

.agents/references/content-style.md

@@ -27,7 +27,7 @@ Repository instructions and the implemented schema and components take precedenc
 - Check `src/content.config.ts` and the installed Nimbus docs schema before adding frontmatter. Do not copy recipe metadata such as `type` or `lastVerified` automatically, or change the schema just to match a recipe. Changelog entries use `title`, `tags`, and `publishedDate`; adapt the changelog recipe to the existing per-entry collection and routes.
 - Check `src/components.ts` and relevant sibling pages for supported MDX components and imports. Use the [component reference](components.md) to choose existing components or plain Markdown. A recipe's component suggestions do not require installing registry UI or changing the portal's Circuit presentation.
 - Follow `AGENTS.md` for root-absolute website links, code blocks, and images. Keep Markdown reference files under `.agents/`, outside website content collections.
-- API reference facts come from the synchronized `openapi.yaml` and Nimbus's prepared model. Do not edit that schema or generated output to satisfy a recipe.
+- API reference facts come from the synchronized `openapi31.json` and Nimbus's prepared model. Do not edit that schema or generated output to satisfy a recipe.
 
 ## Write clear prose and procedures
 

.prettierignore

@@ -4,6 +4,7 @@ dist/
 .nimbus/
 openapi.yaml
 openapi.json
+openapi31.json
 # Imported verbatim from the pinned upstream skills tree.
 /skills/
 # Imported verbatim from the pinned Nimbus source revision.

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Organization
 
-The portal uses Astro with Nimbus. Application source sits in `src/`, with `pages/` for route entry points, `content/` for MDX docs, `layouts/` and `components/` for repository-owned UI (React, Astro, and Circuit UI), and `utils/`/`lib/` for shared logic. Assets live in `src/assets` and `public/`. Build outputs go to `dist/`. Configuration resides in `astro.config.ts`, `nimbus.json`, and `wrangler.jsonc`; adjust them when adding new content types or deployment targets. API documentation is based on `openapi.yaml`, this file is synchronized from outside this repository, do not edit it.
+The portal uses Astro with Nimbus. Application source sits in `src/`, with `pages/` for route entry points, `content/` for MDX docs, `layouts/` and `components/` for repository-owned UI (React, Astro, and Circuit UI), and `utils/`/`lib/` for shared logic. Assets live in `src/assets` and `public/`. Build outputs go to `dist/`. Configuration resides in `astro.config.ts`, `nimbus.json`, and `wrangler.jsonc`; adjust them when adding new content types or deployment targets. API documentation is based on `openapi31.json`, this file is synchronized from outside this repository, do not edit it.
 
 Use Node.js 24.x and the npm version pinned in `package.json`. Install locked dependencies with `npm ci`. The primary branch is `main`.
 

README.md

@@ -105,17 +105,22 @@ accessibility, and working documentation.
 
 ## API Specs
 
-The OpenAPI definition used by the [API Reference](https://developer.sumup.com/api/) is managed in another repository and synchronized into `openapi.yaml`. Do not edit this file directly. If you find a mistake or have an improvement to suggest, [open an issue](https://github.com/sumup/sumup-developer/issues/new).
+The OpenAPI 3.1.0 definition used by the [API Reference](https://developer.sumup.com/api/) is managed in another repository and synchronized into `openapi31.json`. Do not edit this file directly. If you find a mistake or have an improvement to suggest, [open an issue](https://github.com/sumup/sumup-developer/issues/new).
 
-Nimbus serves the API reference at `/api/`, including operation and schema
+Nimbus serves the API reference at `/api/`, including operation and webhook
 pages, alternate Markdown, search, `/api/llms.txt`, documentation MCP access,
 and citation coordinates at `/nimbus-api/coordinates.json`.
 
-`src/lib/api/reference.ts` derives Nimbus's input from `openapi.json` and the
+`src/lib/api/reference.ts` derives Nimbus's input from `openapi31.json` and the
 vendored SDK samples without changing either source. Established operation
 URLs are recorded in `src/lib/api/operationPaths.json`. The projection adds
 access requirements to agent Markdown and converts MDX callouts to CommonMark
-blockquotes. Nimbus shares one operation/schema coordinate namespace, so it
+blockquotes. Tag pages list events from the contract's `webhooks`, grouped by
+their operation tags, with descriptions and links to Nimbus's webhook pages.
+The sidebar nests those pages in an Events group under each associated tag.
+Opening an event expands its tag and Events group; there is no global Webhooks
+group in the sidebar.
+Nimbus shares one operation/schema coordinate namespace, so it
 aliases the colliding `ProcessCheckout` schema to `ProcessCheckoutSchema`
 and updates its references in memory. `/openapi.json` publishes the original
 contract, and `/api/openapi.json` permanently redirects to it. The postbuild
@@ -129,6 +134,15 @@ citation coordinates; our components own the HTML, styles, and presentation.
 API pages use the same `DocsLayout`, navigation, search, mobile menu, theme,
 and page actions as the guides. No separate API theme or Tailwind setup is needed.
 
+Tag overviews put the description beside Endpoints and Events tabs, followed by
+core object schemas on the left and JSON examples on the right. Dedicated schema
+pages are disabled. Former core schema URLs redirect to the corresponding tag
+sections; other former schema URLs redirect to the API overview.
+`src/lib/api/coreObjects.ts` uses a private Nimbus model to prepare the schema
+fields and generate JSON examples. This model does not publish routes. The route
+uses `src/lib/api/tagOverview.ts` to resolve tag events to Nimbus's webhook pages.
+Markdown and MCP include the core object fields and JSON examples inline.
+
 The renderer uses Nimbus's headless disclosure and tab controllers for nested
 properties, expand/collapse all, field deep links, and keyboard navigation.
 Unions show their variants and discriminator mappings. Request samples support

astro.config.ts

@@ -35,7 +35,7 @@ const head = defineNimbusConfig({
       label: "SumUp API",
       spec: apiReference.spec,
       requireOperationId: true,
-      schemaPages: true,
+      schemaPages: false,
       routes: {
         convention: "resource-action-v2",
         operations: apiReference.operations,