Improve documentation for inbound and outbound webhooks

apps/api/package.json

@@ -7,7 +7,7 @@
     "build": "next build",
     "start": "next start",
     "analyze": "ANALYZE=true pnpm build",
-    "stripe": "stripe listen --forward-to localhost:3002/webhooks/stripe",
+    "stripe": "stripe listen --forward-to localhost:3002/webhooks/payments",
     "clean": "git clean -xdf .cache .turbo dist node_modules",
     "format": "biome lint --write .",
     "lint": "biome lint .",

docs/features/analytics/product.mdx

@@ -37,8 +37,8 @@ graph TD
   A[User Action in App] -->|Triggers| B[Clerk Webhook]
   A -->|Triggers| E[Stripe Webhook]
   A -->|Client-Side Call| PostHog
-  B -->|Sends Data| C1[webhooks/clerk]
-  E -->|Sends Data| C2[webhooks/stripe]
+  B -->|Sends Data| C1[webhooks/authentication]
+  E -->|Sends Data| C2[webhooks/payments]
 
   subgraph API
     C1

docs/features/authentication.mdx

@@ -21,8 +21,4 @@ From here, you can use all the pre-built components and hooks provided by Clerk.
 
 ## Webhooks
 
-Clerk uses webhooks to handle authentication events. These are handled in the `POST /webhooks/clerk` route in the `api` app. Make sure you enable the webhook events you need in your Clerk project settings.
-
-### Local Development
-
-Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying your app to a "production" state Vercel project with development environment variables e.g. `staging-api.example.com`. Then you can add this URL to your Clerk project's webhook settings.
+Clerk uses webhooks to handle authentication events and you can send these to your application. Read more about [inbound authentication webhooks](/features/webhooks/inbound#authentication-events).

docs/features/payments.mdx

@@ -1,6 +1,6 @@
 ---
 title: Payments
-description: In-app payments and webhooks with Stripe.
+description: How next-forge handles payments and billing.
 ---
 
 next-forge uses [Stripe](https://stripe.com/) by default for payments and billing. Implementing Stripe in your project is straightforward.
@@ -19,11 +19,7 @@ await stripe.prices.list();
 
 ## Webhooks
 
-Stripe webhooks are handled in the `POST /webhooks/stripe` route in the `api` app. This route constructs the event and then switches on the event type to determine how to process the event.
-
-### Local Development
-
-To test webhooks locally, we've configured the Stripe CLI to forward webhooks to your local server. This will start automatically when you run `pnpm dev`.
+next-forge has a pre-built webhook handler for payment events. Read more about [inbound payment webhooks](/features/webhooks/inbound#payment-events).
 
 ## Anti-Fraud
 

docs/features/webhooks/inbound.mdx

@@ -0,0 +1,26 @@
+---
+title: Inbound Webhooks
+description: Receive inbound webhooks from other services.
+---
+
+next-forge has pre-built webhook handlers for several key services.
+
+## Payment Events
+
+[Payment events](/features/payments) are handled in the `POST /webhooks/payments` route in the `api` app. This route constructs the event and then switches on the event type to determine how to process the event.
+
+<Info>To test webhooks locally, we've configured the Stripe CLI to forward webhooks to your local server. This will start automatically when you run `pnpm dev`.</Info>
+
+## Authentication Events
+
+[Authentication events](/features/authentication) are handled in the `POST /webhooks/auth` route in the `api` app. 
+
+<Tip>Make sure you enable the webhook events you need in your Clerk project settings.</Tip>
+
+### Local Development
+
+Currently there's no way to easily test Clerk webhooks locally, so you'll have to test them in a staging environment. This means deploying your app to a "production" state Vercel project with development environment variables e.g. `staging-api.example.com`. Then you can add this URL to your Clerk project's webhook settings.
+
+## Database Events
+
+One of the most common use cases for inbound webhooks is to notify your application when a database record is created, updated, or deleted. This allows you to react to changes asynchronously, rather than polling the database, cron jobs or other methods.

docs/features/webhooks.mdx → docs/features/webhooks/outbound.mdx

@@ -1,6 +1,6 @@
 ---
-title: Webhooks
-description: Send webhooks to your users using Svix.
+title: Outbound Webhooks
+description: Send outbound webhooks to your users using Svix.
 ---
 
 next-forge supports sending webhooks to your users using [Svix](https://www.svix.com/). Svix is an enterprise-ready webhooks sending service.

docs/migrations/authentication/better-auth.mdx

@@ -268,7 +268,7 @@ const fullOrganization = await auth.api.getFullOrganization({
 });
 ```
 
-```tsx webhooks/stripe/route.ts
+```tsx webhooks/payments/route.ts
 import { clerkClient } from '@repo/auth/server';
 
 const clerk = await clerkClient();

docs/migrations/payments/lemon-squeezy.mdx

@@ -47,15 +47,9 @@ export * from '@lemonsqueezy/lemonsqueezy.js';
 
 ## 4. Update the payments webhook handler
 
-Remove the Stripe webhook handler from the API package...
+Modify the payments webhook handler to use the Lemon Squeezy:
 
-```sh Terminal
-rm apps/api/app/webhooks/stripe/route.ts
-```
-
-... and create a new webhook handler for Lemon Squeezy:
-
-```ts apps/api/app/webhooks/lemon-squeezy/route.ts
+```ts apps/api/app/webhooks/payments/route.ts
 import { NextResponse } from 'next/server';
 
 export const POST = async (request: Request) => {

docs/mint.json

@@ -132,7 +132,10 @@
         "features/storage",
         "features/storybook",
         "features/toolbar",
-        "features/webhooks",
+        {
+          "group": "Webhooks",
+          "pages": ["features/webhooks/inbound", "features/webhooks/outbound"]
+        },
         {
           "group": "SEO",
           "pages": [
@@ -326,7 +329,7 @@
     },
     {
       "source": "/webhooks",
-      "destination": "/features/webhooks"
+      "destination": "/features/webhooks/outbound"
     },
     {
       "source": "/seo",