Webhooks - ai-cmo.dev

ai-cmo.dev currently exposes one inbound webhook for Stripe billing. This page covers signature verification, event handling, and idempotency for developers integrating the webhook endpoint.

Stripe webhook

POST /api/v1/webhooks/stripe Public route. Stripe sends events to this endpoint after checkout sessions complete or expire.

Simulate a Stripe webhook event (local/test only)

curl -X POST http://127.0.0.1:3000/api/v1/webhooks/stripe \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=123456789,v1=test_signature" \
  -d '{"type": "checkout.session.completed", "data": {"object": {"id": "cs_test_..."}}}'

Signature verification

The server verifies the Stripe signature against STRIPE_WEBHOOK_SECRET:

It reads the stripe-signature header from the request.
It calls stripe.webhooks.constructEvent(rawBody, signature, webhookSecret) (or the mock equivalent in local mode).
If verification fails, it returns 400 invalid_signature.

The endpoint fails closed when STRIPE_WEBHOOK_SECRET is unset, returning 503 billing_unavailable.

Events handled

Event type	Action
`checkout.session.completed`	Fulfil the top-up: record the credit grant and mark the receipt as succeeded
`checkout.session.expired`	Mark the receipt as failed
Any other type	Ignored (`"ignored"` status)

Idempotency

Each checkout session is fulfilled at most once. The webhook handler checks the receipt status and the credit_entries unique constraint on (workspace, idem_scope, idempotency_key). Replayed events never double-credit.

Stripe verification in local mode

When STRIPE_MOCK_SENTINEL=enabled, the server uses a deterministic mock client that verifies signatures with HMAC-SHA256 over the raw body using STRIPE_WEBHOOK_SECRET as the key. This mirrors Stripe’s verification closely enough that a tampered body or wrong secret fails identically to production.

Rate limits

The billing checkout endpoint is rate-limited to 12 requests per 60 seconds per workspace.

​Stripe webhook

​Signature verification

​Events handled

​Idempotency

​Stripe verification in local mode

​Rate limits

Stripe webhook

Signature verification

Events handled

Idempotency

Stripe verification in local mode

Rate limits