---
title: "Receive a signed Stripe event"
method: POST
path: "/api/v1/stripe-webhook"
tags: ["Billing", "Integrations"]
---

# Receive a signed Stripe event

`POST /api/v1/stripe-webhook`

Provider callback, not an end-user API. The exact raw JSON body is capped at 512 KiB and verified against `Stripe-Signature` before durable inbox claim or side effects. Provider `event.id` supplies idempotency; terminal duplicates return 200, active leases return 503 for retry, and failures return 500 so Stripe retries. No webhook secret, signature, raw payload or internal exception is returned. This route is excluded from every public MCP surface.

## Headers

- `Stripe-Signature` string, required

## Request body

- StripeWebhookEventRequest — Stripe Event envelope. The exact signed raw bytes, not a reserialized object, are used for verification. Provider extension fields remain typed JSON and are not reflected to callers.
  - `id` string, required — Provider event id and durable idempotency key.
  - `object` 'event'
  - `type` string, required
  - `created` integer
  - `livemode` boolean
  - `api_version` string, nullable
  - `data` object, required
    - `object` object, required
    - `previous_attributes` object

## Response `200`

Event accepted, deliberately ignored, or already terminal. All response bodies are non-secret acknowledgements.

## Other responses

- `400` — Signature missing/invalid, or the raw request stream cannot be read
- `413` — Raw callback body exceeds 512 KiB
- `500` — Inbox persistence or event processing failed; Stripe must retry
- `503` — Another worker owns an active lease or a signed OpenMercantil checkout cannot yet be resolved to its authoritative account owner; Stripe must retry

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/versions/996f96a11758/schema)