---
title: "Stripe Webhook"
method: POST
path: "/api/v1/billing/webhooks/stripe"
tags: ["billing"]
---

# Stripe Webhook

`POST /api/v1/billing/webhooks/stripe`

Apply a Stripe event.

The status code answers one question: *would redelivering this help?*

Stripe retries a non-2xx for three days and disables an endpoint that keeps
failing, so a permanent condition must never answer 5xx — one malformed
payload would otherwise take the webhook down for every customer. A
signature failure (401), a malformed body (400), an event type MAIA does
not act on (204), and any payload this system cannot process (204, logged)
are all permanent for that delivery and are answered without retry.

5xx is reserved for the transient: no secret configured yet, or a Stripe
API call that failed while re-fetching. Those are worth redelivering.

## Headers

- `Stripe-Signature` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-15** `499d0b94aa94` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/billing/webhooks/stripe/post.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/7720763f8bf1?raw)