Stop asking Claude to reinvent Stripe billing.

.udria/production-stripe-billing/spec/webhooks.md

# Webhook ingestion

> Excerpt from `.udria/production-stripe-billing/spec/webhooks.md`.

Stripe verifies the signature. Everything after that is yours, and it is where
the bugs live. This section specifies ingestion; entitlement resolution is
specified in `entitlements.md`, and event ordering in
`idempotency-and-ordering.md`.

## Invariants

The agent MUST satisfy all five before this section is considered implemented.

1. **Signature.** Reject any request whose signature fails `constructEvent`,
   with 400, before the body is parsed or persisted.
2. **Idempotency.** Processing the same `event.id` twice MUST leave the
   database byte-identical to processing it once.
3. **Ordering.** Stripe does not guarantee delivery order. Applying an older
   event after a newer one MUST NOT move billing state backwards.
4. **Durability.** An event that has been acknowledged (2xx) MUST be
   recoverable. An event that failed MUST NOT be acknowledged.
5. **Reconciliation.** Where local state and Stripe disagree, Stripe wins, and
   the disagreement is recorded rather than silently overwritten.

## Ledger table

Ingestion is a two-phase write: record the event, then apply it. The ledger is
the idempotency key and the audit trail.

```sql
create table billing_events (
  id            text primary key,          -- Stripe's event.id
  type          text        not null,
  api_version   text,
  payload       jsonb       not null,
  received_at   timestamptz not null default now(),
  processed_at  timestamptz,
  failed_at     timestamptz,
  failure_count integer     not null default 0,
  last_error    text
);
```

`id` is Stripe's own event id, and it is the primary key. That single choice is
what makes replay safe: the insert is the lock.

```
insert into billing_events (id, type, payload)
values ($1, $2, $3)
on conflict (id) do nothing
returning id
```

Zero rows returned means this event has been seen. Acknowledge with 200 and do
no further work.

## Ordering

Every subscription-shaped event carries the subscription object it describes.
Compare before applying:

- Prefer `created` on the **event**, not `current_period_start` on the object.
- Persist `last_event_at` on the local subscription row.
- If `event.created <= last_event_at`, discard the event as stale. Record the
  discard; do not error.

This is the rule that prevents the common failure where a retried
`customer.subscription.updated` from the cancellation flow lands after the
reactivation that followed it, and quietly revokes a paying customer's access.

## Failure handling

Return a non-2xx **only** when a retry could succeed — a database outage, a
timeout. Return 2xx and record `failed_at` for anything a retry cannot fix
(an event for a customer that does not exist locally, a malformed payload).
Retrying a permanently broken event for three days produces noise, not repair.

`failure_count >= 5` MUST raise an operational alert. Deciding what "alert"
means is the host application's choice; the specification only requires that
silence is not an option.

## Events in scope for V1

| Event | Effect |
| --- | --- |
| `checkout.session.completed` | Link the Stripe customer to the local account |
| `customer.subscription.created` | Create local subscription, grant entitlements |
| `customer.subscription.updated` | Re-resolve plan, period, cancellation and seat allowance |
| `customer.subscription.deleted` | End entitlements at period end, not immediately |
| `invoice.paid` | Clear any dunning state, extend the period |
| `invoice.payment_failed` | Enter dunning; see `subscription-lifecycle.md` |

Events outside this table MUST be recorded in the ledger and ignored. Handling
an event the specification does not cover is out of scope, not a bonus.

.udria/production-stripe-billing/acceptance/tests/webhook-idempotency.spec.ts

// Excerpt from .udria/production-stripe-billing/acceptance/tests/
//   webhook-idempotency.spec.ts
//
// Ships as a real file. Your agent wires `harness` to your schema, then runs
// the suite before it reports the implementation as finished.

import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { harness, type Harness } from "./_harness";

describe("webhook ingestion", () => {
  let h: Harness;

  beforeEach(async () => {
    h = await harness();
    await h.seed.organisation({ id: "org_1", plan: "free" });
    await h.seed.stripeCustomer({ id: "cus_1", organisationId: "org_1" });
  });

  afterEach(() => h.reset());

  it("grants entitlement on a new subscription", async () => {
    await h.post(
      h.event("customer.subscription.created", {
        id: "sub_1",
        customer: "cus_1",
        status: "active",
        items: [{ price: h.prices.pro, quantity: 3 }],
      }),
    );

    expect(await h.entitlements("org_1")).toMatchObject({ plan: "pro", seats: 3 });
  });

  it("has no duplicate effect when the same event is delivered twice", async () => {
    const event = h.event("customer.subscription.created", {
      id: "sub_1",
      customer: "cus_1",
      status: "active",
      items: [{ price: h.prices.pro, quantity: 3 }],
    });

    await h.post(event);
    const afterFirst = await h.snapshot();

    const second = await h.post(event);

    expect(second.status).toBe(200);
    expect(await h.snapshot()).toEqual(afterFirst);
    expect(await h.rows("billing_events")).toHaveLength(1);
  });

  it("rejects an invalid signature before touching the database", async () => {
    const res = await h.postRaw(
      h.event("customer.subscription.created", { id: "sub_1", customer: "cus_1" }),
      { signature: "t=1,v1=deadbeef" },
    );

    expect(res.status).toBe(400);
    expect(await h.rows("billing_events")).toHaveLength(0);
  });

  it("does not move state backwards when events arrive out of order", async () => {
    // Reality: the cancellation is retried and lands after the reactivation.
    const cancelled = h.event(
      "customer.subscription.updated",
      { id: "sub_1", customer: "cus_1", status: "canceled" },
      { created: 1_000 },
    );
    const reactivated = h.event(
      "customer.subscription.updated",
      { id: "sub_1", customer: "cus_1", status: "active", items: [{ price: h.prices.pro }] },
      { created: 2_000 },
    );

    await h.post(reactivated);
    await h.post(cancelled);

    expect(await h.entitlements("org_1")).toMatchObject({ plan: "pro", active: true });
  });

  it("keeps access until period end when a subscription is cancelled", async () => {
    await h.post(
      h.event("customer.subscription.updated", {
        id: "sub_1",
        customer: "cus_1",
        status: "active",
        cancel_at_period_end: true,
        current_period_end: h.daysFromNow(12),
      }),
    );

    expect(await h.entitlements("org_1")).toMatchObject({ plan: "pro", active: true });

    await h.clock.advance({ days: 13 });

    expect(await h.entitlements("org_1")).toMatchObject({ plan: "free", active: false });
  });

  it("acknowledges an unrecoverable event instead of retrying it forever", async () => {
    const res = await h.post(
      h.event("customer.subscription.created", { id: "sub_9", customer: "cus_unknown" }),
    );

    expect(res.status).toBe(200);
    expect(await h.row("billing_events", "failed_at")).not.toBeNull();
  });
});