Wire Ringside spend into Stripe metered billing

20 min

By the end you'll have a working pipeline: Ringside charges land in your webhook, get signed-checked, translate into Stripe meter events, and your customers can open their own billing portal from a Next.js route.

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

// subscribe to chat.completion.finished

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 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 on every attempt. Re-emits on the same attempt share an event id, so your handler can be idempotent.

~/billing

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

✓201 Created

{"id":"whe_7hK2n","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.

Use ringside_spend as the event name so every meter event points at the same bucket. Units are up to you; this tutorial uses micro-cents so fractional usage doesn't round down.

~/billing

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

✓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 HMAC signature

A minimal Express handler. The critical line is the HMAC comparison; you never trust the body until the signature matches the secret from Step 1.

Log the event type + customer id first so you can see the wiring work end-to-end before you layer Stripe on top.

What just happened

Use express.raw() (not express.json()) or Node's built-in raw-body read. HMAC is computed over the exact bytes on the wire - JSON re-serialization will silently break verification.

~/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 sig = req.headers["fc-signature"];

const mac = crypto.createHmac("sha256", process.env.WHSEC).update(req.body).digest("hex");

if (sig !== mac) return res.status(401).end();

const evt = JSON.parse(req.body); console.log(evt.type, evt.data.customer);

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

Pull the Stripe customer id off your own mapping (usually stored on the Ringside Customer's metadata) and post a meter event equal to the call cost.

Ringside events carry cost_usd already converted to dollars. Multiply by 100,000 for micro-cents. Stripe accepts any integer unit, and you pick the rate on the Price.

What just happened

Ringside bills you in fractional dollars. Stripe meters store integers. Pick a unit once (micro-cents is our recommended default) and stay consistent - you can always change the Price markup later without touching the meter math.

~/billing/server.js

// inside the webhook handler:

await stripe.billing.meterEvents.create({

event_name: "ringside_spend",

payload: {

stripe_customer_id: evt.data.metadata.stripe_customer_id,

value: Math.round(evt.data.cost_usd * 100_000) // micro-cents

}

});

✓meter_event_6hJ2 posted ($0.0019)

█

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 →