---
title: "Stripe Lifecycle Webhook"
method: POST
path: "/webhooks/stripe"
tags: ["Webhooks"]
---

# Stripe Lifecycle Webhook

`POST /webhooks/stripe`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/webhooks/stripe`
- Auth: none declared

Fan out a Stripe lifecycle event to Slack + Loops.so.

Called by ``kolens-web/app/api/stripe/webhook/route.ts`` AFTER the
Stripe signature has been verified on Vercel. Auth is the shared
``X-Admin-Secret`` (same pattern as ``/api/workspaces/.../billing/
credit-grant``). Returns 200 with ``{received, processed,
slack_sent, loops_sent}`` so the BFF can log what fired without
needing to wait on either downstream provider.

Event types handled:

* ``checkout.session.completed`` →
  Slack: ``:tada: New paying customer: <email> (<plan>, <amount>)``
  Loops: ``subscription_purchased``
* ``customer.subscription.deleted`` →
  Slack: ``:disappointed: Churned customer: <email>``
  Loops: ``subscription_canceled``
* ``invoice.payment_failed`` →
  Slack: ``:warning: Payment failed: <email>``
  Loops: ``payment_failed``

Any other event type returns 200 with ``processed=False`` —
unknown types are not an error. All integrations gracefully no-op
when their env keys are unset; the response reflects what actually
fired.

## Headers

- `X-Admin-Secret` string, nullable

## Request body

- StripeLifecycleEvent: Minimal payload the Vercel BFF forwards after signature verification. Stripe's native event shape is huge; we accept just the fields the fanout actually uses. ``stripe_event_id`` is the ``evt_...`` id Stripe sends — used for idempotency. ``type`` is the Stripe event type (``checkout.session.completed`` etc.).
  - `stripe_event_id` string, required
  - `type` string, required
  - `email` string, nullable
  - `plan` string, nullable
  - `amount_cents` integer, nullable
  - `currency` string, nullable
  - `workspace_slug` string, nullable

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)