---
title: "Stripe Webhook"
method: POST
path: "/billing/stripe-webhook"
tags: ["billing"]
---

# Stripe Webhook

`POST /billing/stripe-webhook`

Handle Stripe webhook events.

Verifies the Stripe signature, deduplicates by event id, and routes the
event to its billing-lifecycle handler. Unprotected (no auth) but
signature-verified.

Events handled: checkout.session.completed, invoice.paid,
invoice.payment_failed, customer.subscription.deleted / .updated,
payment_method.attached / .detached, charge.refunded, customer.deleted,
radar.early_fraud_warning.created.

Args:
    request: Inbound FastAPI request carrying the raw Stripe payload.
    stripe_signature: Value of the ``stripe-signature`` header.

Returns:
    ``{"status": "success"}`` once the event is processed.

Raises:
    HTTPException: 500 when the webhook secret is unconfigured or
        processing fails; 400 for an invalid signature.

## Headers

- `stripe-signature` string, nullable

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/revisions/31dfe831e079/schema)