---
title: "Receive Stripe billing webhook"
method: POST
path: "/v1/billing/webhook"
tags: ["Billing"]
---

# Receive Stripe billing webhook

`POST /v1/billing/webhook`

## Request

- Base URL: `https://api.agentry.sh`
- URL: `https://api.agentry.sh/v1/billing/webhook`
- Auth: none declared

Stripe-signed webhook for checkout.session.completed and customer.subscription.* events. The raw body is stream-bounded to 262144 bytes before signature verification. Required Stripe event id/type/created fields are persisted as a payload-hash-bound replay receipt; per-subscription ordering rejects older delivery before state can roll backward. Stripe event ids are opaque, so different events with the same created second are recorded as ambiguous_order and never automatically applied until a newer provider event resolves state. User updates require no account-deletion fence; fenced events remain durable deletion evidence. This endpoint uses Stripe-Signature, not API-key auth.

## Request body

- object

## Response `200`

OK

- object
  - `received` boolean, required
  - `event_id` string, nullable
  - `event_type` string, nullable
  - `handled` boolean, required
  - `applied` boolean, required
  - `delivery_status` 'applied' | 'stale' | 'ambiguous_order' | 'account_deletion_fenced' | 'unmatched' | 'unhandled', required
  - `idempotent_replay` boolean, required
  - `user_id` string, nullable
  - `plan` string, nullable
  - `billing_status` string, nullable
  - `next_action` string

## Other responses

- `default`: Error

---

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