Webhooks & Integration

Reference for Stripe webhook events, integration points, and rate limits across all API routes.

Stripe webhooks

MyClaude listens for Stripe events at a single endpoint:

POST /api/stripe/webhooks

This endpoint is exempt from CSRF origin checks and Bearer token auth. It authenticates exclusively via Stripe webhook signature verification.

Handled events

All other event types are acknowledged with 200 and silently ignored.

Webhook security

Signature verification

Every incoming webhook is verified using stripe.webhooks.constructEvent() with the STRIPE_WEBHOOK_SECRET. Requests with missing or invalid signatures receive 400 and are not processed.

Request arrives
    |
    v
Extract stripe-signature header
    |
    v
constructEvent(body, signature, secret)
    |-- Invalid --> 400 (no retry)
    |-- Valid   --> Process event

Idempotency

Order creation uses the Stripe session ID as the Firestore document ID. This guarantees idempotency:

• First delivery: transaction creates the order document
• Retry delivery: transaction reads the existing document, detects duplicate, skips creation
• No duplicate orders, no duplicate stat increments

The check runs inside a Firestore transaction, so concurrent webhook retries are also safe.

Atomic order creation

The checkout.session.completed handler executes a single Firestore transaction that atomically:

1. Creates the orders/{sessionId} document
2. Increments products/{id}.stats.purchaseCount
3. Increments users/{sellerId}.stats.totalRevenue and stats.totalSales, adds 50 XP
4. Increments users/{buyerId}.stats.productsBought, adds 10 XP

If any step fails, the entire transaction rolls back. Stripe receives 503, which triggers automatic retry with exponential backoff.

Price verification

The webhook handler re-reads the product price from Firestore and cross-checks against session.amount_total. If a price change occurred between checkout creation and webhook delivery, the discrepancy is logged but the order is still created using Stripe's authoritative amount (what was actually charged).

Platform fee is recalculated server-side at 8% of the actual charged amount -- never from client metadata.

Refund handling

The charge.refunded handler:

1. Looks up the order by stripePaymentIntentId
2. Runs an atomic transaction: sets status: "refunded", decrements seller revenue and sales count, decrements buyer purchase count
3. Creates a notification in the seller's notifications subcollection (fire-and-forget, outside transaction)

Already-refunded orders are skipped (idempotent).

Integration points

CLI (myclaude)

The myclaude CLI communicates with dedicated API routes optimized for terminal output.

All CLI commands support a --json flag for machine-readable output, suitable for piping into jq or downstream scripts.

MCP server

MyClaude exposes tools via Model Context Protocol for agent integration. Agents can search products, read metadata, and trigger installations through MCP tool calls. See the MCP Tool Schemas reference for the full tool catalog.

Docs A-Surface

Requests to /docs.md or /docs/{slug}.md are rewritten to return raw Markdown content from the documentation system. This enables AI agents to fetch docs context without parsing HTML.

Rate limits

All routes are rate-limited per IP address within a 60-second window. Two strategies exist:

Complete rate limit table

Rate limit response

When a rate limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": "Too many requests"
}

The Retry-After header indicates seconds until the window resets.

Error codes

All API errors follow a consistent JSON format:

{
  "error": "Human-readable error message"
}

For the full error taxonomy, see /specs/error-codes.yaml in the repository.

Related pages

• API Overview -- Base URL, auth model, endpoint groups
• Payments API -- Checkout and Connect endpoint details
• Security Model -- Architecture-level security controls
• MCP Tool Schemas -- Agent integration reference
• Self-Hosting -- Deployment and webhook configuration