Changelog (#399)

* feat: add changelog feature and update site navigation - Introduced a new Changelog page with pagination and detailed entry views. - Added components for displaying changelog entries, pagination, and entry details. - Updated site navigation to include a link to the new Changelog page. - Enhanced localization for changelog-related texts in marketing.json. * refactor: enhance Changelog page layout and entry display - Increased the number of changelog entries displayed per page from 2 to 20 for better visibility. - Improved the layout of the Changelog page by adjusting the container styles and removing unnecessary divs. - Updated the ChangelogEntry component to enhance the visual presentation of entries, including a new date badge with an icon. - Refined the CSS styles for Markdoc headings to improve typography and spacing. * refactor: enhance Changelog page functionality and layout - Increased the number of changelog entries displayed per page from 20 to 50 for improved user experience. - Updated ChangelogEntry component to make the highlight prop optional and refined the layout for better visual clarity. - Adjusted styles in ChangelogHeader and ChangelogPagination components for a more cohesive design. - Removed unnecessary order fields from changelog markdown files to streamline content management. * feat: enhance Changelog entry navigation and data loading - Refactored ChangelogEntry page to load previous and next entries for improved navigation. - Introduced ChangelogNavigation component to facilitate navigation between changelog entries. - Updated ChangelogDetail component to display navigation links and entry details. - Enhanced data fetching logic to retrieve all changelog entries alongside the current entry. - Added localization keys for navigation text in marketing.json. * Update package dependencies and enhance documentation layout - Upgraded various packages including @turbo/gen and turbo to version 2.6.0, and react-hook-form to version 7.66.0. - Updated lucide-react to version 0.552.0 across multiple packages. - Refactored documentation layout components for improved styling and structure. - Removed deprecated loading components and adjusted navigation elements for better user experience. - Added placeholder notes in changelog entries for clarity.
2025-11-01 11:59:52 +07:00
parent a920dea2b3
commit 116d41a284
73 changed files with 5638 additions and 558 deletions
--- a/apps/web/content/documentation/billing/webhooks.mdoc
+++ b/apps/web/content/documentation/billing/webhooks.mdoc
@@ -0,0 +1,194 @@
+---
+title: "Webhook Integration"
+description: "Setting up and handling payment provider webhooks for subscription events."
+publishedAt: 2024-04-11
+order: 2
+status: "published"
+---
+
+> **Note:** This is mock/placeholder content for demonstration purposes.
+
+Webhooks notify your application when billing events occur, ensuring your app stays synchronized with your payment provider.
+
+## Why Webhooks?
+
+Webhooks are essential for:
+- **Real-time updates** - Instant notification of payment events
+- **Reliability** - Handles events even if users close their browser
+- **Security** - Server-to-server communication
+- **Automation** - Automatic subscription status updates
+
+## Webhook Endpoint
+
+Your webhook endpoint receives events from the payment provider:
+
+```typescript
+// app/api/billing/webhook/route.ts
+export async function POST(request: Request) {
+  const body = await request.text();
+  const signature = request.headers.get('stripe-signature');
+
+  // Verify webhook signature
+  const event = stripe.webhooks.constructEvent(
+    body,
+    signature,
+    process.env.STRIPE_WEBHOOK_SECRET
+  );
+
+  // Handle the event
+  await handleBillingEvent(event);
+
+  return new Response('OK', { status: 200 });
+}
+```
+
+## Common Events
+
+### Subscription Created
+```typescript
+case 'customer.subscription.created':
+  await prisma.subscription.create({
+    data: {
+      id: event.data.object.id,
+      accountId: event.data.object.metadata.accountId,
+      status: 'active',
+      planId: event.data.object.items.data[0].price.id,
+      currentPeriodEnd: new Date(event.data.object.current_period_end * 1000),
+    },
+  });
+  break;
+```
+
+### Subscription Updated
+```typescript
+case 'customer.subscription.updated':
+  await prisma.subscription.update({
+    where: { id: event.data.object.id },
+    data: {
+      status: event.data.object.status,
+      planId: event.data.object.items.data[0].price.id,
+      currentPeriodEnd: new Date(event.data.object.current_period_end * 1000),
+    },
+  });
+  break;
+```
+
+### Subscription Deleted
+```typescript
+case 'customer.subscription.deleted':
+  await prisma.subscription.update({
+    where: { id: event.data.object.id },
+    data: {
+      status: 'canceled',
+      canceledAt: new Date(),
+    },
+  });
+  break;
+```
+
+### Payment Failed
+```typescript
+case 'invoice.payment_failed':
+  const subscription = await prisma.subscription.findUnique({
+    where: { id: event.data.object.subscription },
+  });
+
+  // Send payment failure notification
+  await sendPaymentFailureEmail(subscription.accountId);
+  break;
+```
+
+## Setting Up Webhooks
+
+### Stripe
+
+1. **Local Development** (using Stripe CLI):
+```bash
+stripe listen --forward-to localhost:3000/api/billing/webhook
+```
+
+2. **Production**:
+- Go to Stripe Dashboard → Developers → Webhooks
+- Add endpoint: `https://yourdomain.com/api/billing/webhook`
+- Select events to listen to
+- Copy webhook signing secret to your `.env`
+
+### Paddle
+
+1. **Configure webhook URL** in Paddle dashboard
+2. **Add webhook secret** to environment variables
+3. **Verify webhook signature**:
+
+```typescript
+const signature = request.headers.get('paddle-signature');
+const verified = paddle.webhooks.verify(body, signature);
+
+if (!verified) {
+  return new Response('Invalid signature', { status: 401 });
+}
+```
+
+## Security Best Practices
+
+1. **Always verify signatures** - Prevents unauthorized requests
+2. **Use HTTPS** - Encrypts webhook data in transit
+3. **Validate event data** - Check for required fields
+4. **Handle idempotently** - Process duplicate events safely
+5. **Return 200 quickly** - Acknowledge receipt, process async
+
+## Error Handling
+
+```typescript
+async function handleBillingEvent(event: Event) {
+  try {
+    await processEvent(event);
+  } catch (error) {
+    // Log error for debugging
+    console.error('Webhook error:', error);
+
+    // Store failed event for retry
+    await prisma.failedWebhook.create({
+      data: {
+        eventId: event.id,
+        type: event.type,
+        payload: event,
+        error: error.message,
+      },
+    });
+
+    // Throw to trigger provider retry
+    throw error;
+  }
+}
+```
+
+## Testing Webhooks
+
+### Using Provider's CLI Tools
+
+```bash
+# Stripe
+stripe trigger customer.subscription.created
+
+# Test specific scenarios
+stripe trigger payment_intent.payment_failed
+```
+
+### Manual Testing
+
+```bash
+curl -X POST https://your-app.com/api/billing/webhook \
+  -H "Content-Type: application/json" \
+  -H "stripe-signature: test_signature" \
+  -d @test-event.json
+```
+
+## Monitoring
+
+Track webhook delivery:
+- Response times
+- Success/failure rates
+- Event processing duration
+- Failed events requiring manual intervention
+
+Most providers offer webhook monitoring dashboards showing delivery attempts and failures.