# /webhooks/payments (auxiliary)

Source-derived auxiliary endpoint contract, authentication, request validation, responses, and errors.

Source: https://docs.minds.sh/docs/api/platform/reference/auxiliary--webhooks-payments



This is the **auxiliary** service route. Its origin and authentication are described in [Platform API overview](/docs/api/platform) and [Authentication](/docs/api/platform/authentication). A path shared by another service is a different endpoint.

| Property                       | Contract                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------ |
| Methods                        | POST                                                                           |
| Path                           | `/webhooks/payments`                                                           |
| Path parameters                | None                                                                           |
| Query parameters read in route | None read directly; schema validation below may define additional fields       |
| Headers read in route          | No additional direct header reads; authentication helpers may read credentials |

## Authentication and access [#authentication-and-access]

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

## Method behavior [#method-behavior]

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 [#post]

```typescript
POST = async (request: Request): Promise<Response> => {
  if (!env.STRIPE_WEBHOOK_SECRET) {
    return NextResponse.json({ message: 'Not configured', ok: false });
  }

  try {
    const body = await request.text();
    const headerPayload = await headers();
    const signature = headerPayload.get('stripe-signature');

    if (!signature) {
      throw new Error('missing stripe-signature header');
    }

    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      env.STRIPE_WEBHOOK_SECRET
    );

    switch (event.type) {
      case 'checkout.session.completed': {
        await handleCheckoutSessionCompleted(event.data.object);
        break;
      }
      case 'subscription_schedule.canceled': {
        await handleSubscriptionScheduleCanceled(event.data.object);
        break;
      }
      default: {
        log.warn(`Unhandled event type ${event.type}`);
      }
    }

    await analytics.shutdown();

    return NextResponse.json({ result: event, ok: true });
  } catch (error) {
    const message = parseError(error);

    log.error(message);

    return NextResponse.json(
      {
        message: 'something went wrong',
        ok: false,
      },
      { status: 500 }
    );
  }
}
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:34`.

## Response and error branches [#response-and-error-branches]

Literal HTTP statuses in the route: 500. Shared management error classes are defined in [Errors and responses](/docs/api/platform/errors).

```typescript
NextResponse.json({ message: 'Not configured', ok: false })
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:36`.

```typescript
new Error('missing stripe-signature header')
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:45`.

```typescript
NextResponse.json({ result: event, ok: true })
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:70`.

```typescript
parseError(error)
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:72`.

```typescript
NextResponse.json(
      {
        message: 'something went wrong',
        ok: false,
      },
      { status: 500 }
    )
```

Source: `minds-ui/apps/api/app/webhooks/payments/route.ts:76`.

## Evidence [#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/app/webhooks/payments/route.ts`. SHA-256: `3247f3ed0e446ab123f8554c41f1102b29c0dbd520a611924a54fad6ed56a86d`.