Wire Ringside spend into Stripe metered billing

20 min

Selling access to an AI model is a resale business, and resale only works if you know your cost of goods to the fraction of a cent. That's the whole problem here. Every call your users make costs you a small, awkward, non-round number, and you need to turn a stream of those into a clean monthly invoice with your markup on top. Ringside tells you what each call consumed as it happens. Stripe knows how to turn a running tally into a bill. This tutorial is the wire between them: a webhook lands, you translate it into a meter tick, and at month end Stripe charges the card. You never build an invoice.

Prerequisites

• A Ringside API key (do the quickstart first if you don't have one)
• A Stripe account with billing enabled + the Stripe CLI installed
• Node 20+ with a tunnel (ngrok, Cloudflare Tunnel, or deployed app)
• Your end-users already mapped to Stripe Customer IDs
• 20 minutes

Step 1

Register a webhook endpoint

// POST /v1/webhooks

Ringside emits an event every time a chargeable API call completes. Register the URL of your receiver and pick the events you care about. The endpoint is /v1/webhooks and the id you get back is prefixed wh_.

The signing secret comes back in the response once. Store it in an env var. You'll use it to HMAC-verify every delivery.

What just happened

Ringside retries deliveries with exponential backoff on any non-2xx, and stamps x-fc-signature, x-fc-event-id, x-fc-event-type and x-fc-delivery-id on every attempt. Retries of the same event share an event id, so key your handler on x-fc-event-id to stay idempotent. Treat delivery as best-effort: reconcile against the usage API on a schedule rather than assuming every event arrived.

~/billing

$ curl -X POST https://api.fightclub.pro/v1/webhooks -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://billing.example.com/ringside","events":["chat.completion.finished"]}'

✓200 OK

{"id":"wh_9f3c1a...","url":"https://billing.example.com/ringside",

"events":["chat.completion.finished"],"secret":"whsec_xY9k2..."}

# Save the secret now - shown once.

█

Step 2

Create a Stripe meter + metered Price

// define the billable unit

A Stripe meter is the server-side aggregator. A metered Price attaches a rate to it. You can run both from the Stripe CLI or the dashboard.

We meter tokens, because tokens are what the Ringside event actually carries. Use ringside_tokens as the event name so every meter event points at the same bucket, and put your price-per-token (cost plus your margin) on the Stripe Price.

~/billing

$ stripe billing meters create --display-name "Ringside tokens" --event-name ringside_tokens

✓mtr_1PqAz9... created

$ stripe prices create --product prod_ai --unit-amount 0 --currency usd --recurring[usage_type]=metered --recurring[meter]=mtr_1PqAz9

✓price_1PqB0k... created (metered)

█

Step 3

Receive the webhook

// verify the x-fc-signature HMAC

A minimal Express handler. The critical part is the signature check, and it has a specific shape worth getting right. The header is x-fc-signature and its value is t=<unix_ts>,v1=<hex>.

The HMAC is computed over <ts>.<raw_body> — the timestamp, a literal dot, then the body. Hashing the body on its own will never match. Compare the digests in constant time and reject anything outside a 5-minute window.

What just happened

Use express.raw() (not express.json()) or Node's built-in raw-body read. The HMAC covers the exact bytes on the wire - JSON re-serialization silently breaks verification. During a secret rotation a single delivery can carry two v1= pairs; accept the delivery if either matches a secret you hold.

~/billing/server.js

$ cat > server.js

import express from "express";

import crypto from "crypto";

const app = express();

app.post("/ringside", express.raw({type:"application/json"}), (req, res) => {

const header = req.headers["x-fc-signature"] || "";

const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=")));

const ts = parts.t;

if (Math.abs(Date.now()/1000 - Number(ts)) > 300) return res.status(401).end();

const expected = crypto.createHmac("sha256", process.env.WHSEC)

.update(`${ts}.${req.body}`).digest("hex"); // ts + "." + RAW body

const got = Buffer.from(parts.v1 || "", "hex");

const want = Buffer.from(expected, "hex");

if (got.length !== want.length || !crypto.timingSafeEqual(got, want))

return res.status(401).end();

const evt = JSON.parse(req.body);

console.log(evt.type, evt.data.customer_id);

res.status(200).end(); });

$ node server.js

✓listening on :3000

chat.completion.finished cus_a1b2

█

Step 4

Post a Stripe meter event from the handler

// stripe.billing.meterEvents.create

The chat.completion.finished payload is {customer_id, id, model, usage, finish_reason}, where usage holds prompt_tokens, completion_tokens and total_tokens.

Note what is not there: the event carries no dollar figure and no metadata blob. So you meter the token count, and you look up the Stripe customer from your own store, keyed on the customer_id the event gives you. The money is decided by the rate on your Stripe Price, not by a field on the event.

What just happened

If you need the dollar cost rather than a token count, read it from the usage API (GET /v1/customers/<id>/usage) on a schedule and reconcile - that endpoint computes per-period spend. The webhook is the low-latency signal; the usage API is the source of truth.

~/billing/server.js

// inside the webhook handler, after verification:

const { customer_id, model, usage } = evt.data;

// your own mapping: Ringside customer -> Stripe customer

const stripeCustomerId = await db.stripeIdFor(customer_id);

await stripe.billing.meterEvents.create({

event_name: "ringside_tokens",

payload: {

stripe_customer_id: stripeCustomerId,

value: String(usage.total_tokens) // integer, from the event

}

});

✓meter_event_6hJ2 posted (19 tokens)

█

Step 5

Self-serve billing portal

// stripe.billingPortal.sessions.create

Drop a Next.js route handler that mints a billing-portal session for the signed-in user's Stripe customer id.

Redirect the user to the returned URL and Stripe handles invoice downloads, card updates, and cancellation. No custom UI to build.

app/api/portal/route.ts

$ cat > app/api/portal/route.ts

import { NextResponse } from "next/server";

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET!);

export async function POST(req: Request) {

const { stripeCustomerId } = await req.json();

const session = await stripe.billingPortal.sessions.create({

customer: stripeCustomerId,

return_url: "https://app.example.com/billing"

});

return NextResponse.json({ url: session.url });

}

✓Customers now self-serve invoices + card updates

█

You built it.

Ringside usage flows to your webhook, gets HMAC-verified, translates to Stripe meter events, and your customers self-serve invoices through the portal. Your margin is the difference between the Ringside cost and the Stripe Price you set.

Example: webhook delivery + retries →Endpoint reference: webhooks →