/api/webhooks/billing/stripe (management)

This is the management service route. Its origin and authentication are described in Platform API overview and Authentication. A path shared by another service is a different endpoint.

Property	Contract
Methods	POST, GET
Path	`/api/webhooks/billing/stripe`
Path parameters	None
Query parameters read in route	None read directly; schema validation below may define additional fields
Headers read in route	`stripe-signature`

Authentication and access

Webhook-specific signature or verification handler; not a customer bearer-token endpoint. See the handler and signing setup.

The handler excerpt preserves field validation, response envelopes, cookie changes, and exception branches. Values returned by service helpers retain their named response type above; for passthrough routes, the upstream response is authoritative.

POST

export async function POST(request: Request) {
  if (!process.env.STRIPE_WEBHOOK_SECRET) {
    console.error('[billing] STRIPE_WEBHOOK_SECRET not configured')
    return NextResponse.json(
      { error: 'Stripe webhook not configured' },
      { status: 503 }
    )
  }

  const signature = request.headers.get('stripe-signature')
  if (!signature) {
    return NextResponse.json(
      { error: 'Missing stripe-signature header' },
      { status: 400 }
    )
  }

  const body = await request.text()

  let event
  try {
    event = verifyStripeWebhook(body, signature)
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Invalid signature'
    return NextResponse.json({ error: message }, { status: 400 })
  }

  try {
    await handleStripeWebhook(event)
  } catch (error) {
    console.error('[billing] Stripe webhook processing failed:', error)
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    )
  }

  return NextResponse.json({ received: true }, { status: 200 })
}

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:14.

GET

export async function GET() {
  return NextResponse.json({
    status: 'active',
    webhook: 'stripe',
    timestamp: new Date().toISOString(),
  })
}

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:54.

Response and error branches

Literal HTTP statuses in the route: 200, 400, 500, 503. Shared management error classes are defined in Errors and responses.

NextResponse.json(
      { error: 'Stripe webhook not configured' },
      { status: 503 }
    )

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:17.

NextResponse.json(
      { error: 'Missing stripe-signature header' },
      { status: 400 }
    )

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:25.

NextResponse.json({ error: message }, { status: 400 })

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:38.

NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    )

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:45.

NextResponse.json({ received: true }, { status: 200 })

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:51.

NextResponse.json({
    status: 'active',
    webhook: 'stripe',
    timestamp: new Date().toISOString(),
  })

Source: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts:55.

Service dependencies

minds-ui/apps/api-service/lib/billing/webhooks.ts

Evidence

Generated from the local source snapshot on 2026-09-12. This page documents implemented code and does not certify a deployed service, permissions configuration, or successful provider operation.

Source file: minds-ui/apps/api-service/app/api/webhooks/billing/stripe/route.ts. SHA-256: 8edb8d286b581035ee7721720854e17647b3a40a6966a96c5dc33a9b2cbe3e81.