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

MyClaude processes Stripe checkout, refund, and account lifecycle events. All other event types are acknowledged with 200 and silently ignored. Event handling is idempotent — replayed webhooks do not create duplicate records.

Webhook security

Signature verification

Every incoming webhook is cryptographically verified using Stripe's signature verification. Requests with missing or invalid signatures receive 400 and are not processed.

Request arrives
    |
    v
Extract stripe-signature header
    |
    v
Verify signature against webhook secret
    |-- Invalid --> 400 (no retry)
    |-- Valid   --> Process event

Idempotency

Order creation uses the Stripe session ID as a unique key. This guarantees idempotency:

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

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

Order processing

Order creation, stat updates, and XP credits are executed atomically in a single database transaction. If any step fails, the entire transaction rolls back and Stripe retries automatically with exponential backoff.

Platform fee is always calculated server-side — never from client metadata. Refund handling is also atomic and idempotent.

Integration points

CLI (myclaude)

The myclaude CLI communicates with dedicated server routes. All 29 commands support --json for machine-readable output. See the CLI Commands Reference for the full command catalog.

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 endpoints are rate-limited per IP address. Read endpoints use a standard strategy; mutation endpoints use a stricter strategy. When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

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
• CLI Commands -- full CLI reference for all 29 commands