Webhook

Author: yanboishere

.kiro/specs/workwork-ledger-mvp/tasks.md

@@ -201,23 +201,23 @@
     - 创建 Checkout Session 并重定向
     - _需求: 6.2_
 
-- [ ] 12. Webhook 处理
-  - [ ] 12.1 实现 Stripe Webhook 端点
+- [x] 12. Webhook 处理
+  - [x] 12.1 实现 Stripe Webhook 端点
     - 签名验证
     - 幂等性处理（记录已处理的 eventId）
     - _需求: 6.4_
-  - [ ] 12.2 实现支付成功处理逻辑
+  - [x] 12.2 实现支付成功处理逻辑
     - 更新发票状态为 paid
     - 创建账本条目
     - _需求: 6.4, 5.7_
-  - [ ] 12.3 编写属性测试：支付完成创建账本条目
+  - [x] 12.3 编写属性测试：支付完成创建账本条目
     - **属性 13: 支付完成创建账本条目**
     - **验证: 需求 5.7, 8.1**
-  - [ ] 12.4 实现支付失败处理逻辑
+  - [x] 12.4 实现支付失败处理逻辑
     - 记录错误日志
     - 保持发票状态不变
     - _需求: 6.7_
-  - [ ] 12.5 编写属性测试：支付验证失败状态不变
+  - [x] 12.5 编写属性测试：支付验证失败状态不变
     - **属性 14: 支付验证失败状态不变**
     - **验证: 需求 6.7**
 

src/app/api/webhooks/stripe/route.ts

@@ -0,0 +1,131 @@
+/**
+ * Stripe Webhook Endpoint
+ * Handles Stripe webhook events with signature verification and idempotency
+ * _需求: 6.4_
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { StripeAdapter } from '@/server/payment/stripe-adapter';
+import {
+  processWebhookWithIdempotency,
+  extractInvoiceIdFromEvent,
+  isPaymentSuccessEvent,
+  isPaymentFailedEvent,
+} from '@/server/payment/webhook.service';
+import {
+  handlePaymentSuccess,
+  handlePaymentFailure,
+} from '@/server/payment/webhook.handlers';
+import { PaymentError, PaymentErrorCodes } from '@/server/payment/types';
+
+/**
+ * POST /api/webhooks/stripe
+ * Receives and processes Stripe webhook events
+ */
+export async function POST(request: NextRequest) {
+  try {
+    // Get raw body for signature verification
+    const rawBody = await request.text();
+    const signature = request.headers.get('stripe-signature');
+
+    if (!signature) {
+      console.error('[Stripe Webhook] Missing stripe-signature header');
+      return NextResponse.json(
+        { error: 'Missing signature' },
+        { status: 400 }
+      );
+    }
+
+    // Get webhook secret from environment
+    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+    if (!webhookSecret) {
+      console.error('[Stripe Webhook] STRIPE_WEBHOOK_SECRET not configured');
+      return NextResponse.json(
+        { error: 'Webhook not configured' },
+        { status: 500 }
+      );
+    }
+
+    // Create Stripe adapter for webhook verification
+    const stripeAdapter = new StripeAdapter({
+      provider: 'stripe',
+      apiKey: process.env.STRIPE_SECRET_KEY || '',
+      webhookSecret,
+    });
+
+    // Verify webhook signature and parse event
+    let event;
+    try {
+      event = await stripeAdapter.verifyWebhook(rawBody, signature);
+    } catch (error) {
+      if (error instanceof PaymentError && error.code === PaymentErrorCodes.WEBHOOK_VERIFICATION_FAILED) {
+        console.error('[Stripe Webhook] Signature verification failed:', error.message);
+        return NextResponse.json(
+          { error: 'Invalid signature' },
+          { status: 400 }
+        );
+      }
+      throw error;
+    }
+
+    console.log(`[Stripe Webhook] Received event: ${event.type} (${event.id})`);
+
+    // Process with idempotency check
+    const { alreadyProcessed } = await processWebhookWithIdempotency(
+      'stripe',
+      event.id,
+      async () => {
+        // Extract invoice ID from event metadata
+        const invoiceId = extractInvoiceIdFromEvent(event);
+
+        if (!invoiceId) {
+          console.log(`[Stripe Webhook] Event ${event.id} has no invoiceId in metadata, skipping`);
+          return { skipped: true };
+        }
+
+        // Handle payment success events
+        if (isPaymentSuccessEvent(event.type)) {
+          console.log(`[Stripe Webhook] Processing payment success for invoice ${invoiceId}`);
+          const result = await handlePaymentSuccess(invoiceId, {
+            pspProvider: 'stripe',
+            pspPaymentId: event.data.paymentId,
+            checkoutSessionId: event.data.checkoutSessionId,
+            amount: event.data.amount,
+            currency: event.data.currency,
+          });
+          return result;
+        }
+
+        // Handle payment failure events
+        if (isPaymentFailedEvent(event.type)) {
+          console.log(`[Stripe Webhook] Processing payment failure for invoice ${invoiceId}`);
+          const result = await handlePaymentFailure(invoiceId, {
+            eventType: event.type,
+            pspProvider: 'stripe',
+            errorMessage: `Payment ${event.type.replace('_', ' ')}`,
+          });
+          return result;
+        }
+
+        // Unhandled event type
+        console.log(`[Stripe Webhook] Unhandled event type: ${event.type}`);
+        return { skipped: true, reason: 'unhandled_event_type' };
+      }
+    );
+
+    if (alreadyProcessed) {
+      console.log(`[Stripe Webhook] Event ${event.id} already processed, skipping`);
+    }
+
+    // Always return 200 to acknowledge receipt
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    console.error('[Stripe Webhook] Error processing webhook:', error);
+    
+    // Return 500 for unexpected errors (Stripe will retry)
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}

src/server/payment/index.ts

@@ -6,3 +6,5 @@ export * from './types';
 export * from './stripe-adapter';
 export * from './credentials';
 export { getPaymentGateway } from './gateway-factory';
+export * from './webhook.service';
+export * from './webhook.handlers';