Webhook Fulfillment Kit

The five failures it prevents

Every one of these happened in a production Stripe integration before it became a rule here:

1. Two winners, one job. The success redirect and the webhook race each other and both try to fulfill. Whoever loses must return *success* — the buyer paid, and the second caller is not an error case. 2. Retries are not duplicates. Providers retry on any non-2xx. Return 500 on an event you already processed and you receive it forever. 3. A non-critical side effect must never abort fulfillment. A seller payout that threw stranded *paid* orders mid-provisioning. Entitlement first; everything optional degrades to pending. 4. Out-of-order delivery is normal. A terminal state must never be walked backwards by a late-arriving earlier event. 5. Verify before you trust. The signature check runs before the body is parsed as anything meaningful; a failure is a 400 that never reaches fulfillment.

Why not just generate it

The code isn't the scarce part — that list is. This package's own test suite caught a double-fulfillment bug in its own first draft: `processing` was a legal source state for the atomic claim, so the second racer re-claimed an in-flight order and both fulfilled. That is precisely the bug the kit exists to prevent, written by someone who had just finished writing down the rule.

Proof

23 tests, including a real concurrency test that fires the redirect and the webhook simultaneously and asserts the work happened exactly once.

What you implement

A store with four single-query methods. The important one is `compareAndSetState` — a single `UPDATE ... WHERE state IN (...)` that reports whether the row changed. That return value is the entire race resolution. An in-memory implementation ships for tests.

Delivery

Source delivered as a private repository invite within 24 hours of purchase. Single-product commercial license: use and modify in any number of products; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export async function fulfillOnce( store: FulfillmentStore, input: FulfillInput, ): Promise<FulfillOutcome>;
  export function createMemoryStore(seed: OrderRecord[] = []): FulfillmentStore &;