convex-http-actions_skill

Overview

This skill provides a reusable toolkit for building HTTP endpoints in Convex apps, covering routing, request parsing, authentication, CORS, and webhook signature validation. It packages practical patterns and templates to integrate external APIs, process webhooks, and expose custom API routes safely and reliably. The focus is on production-ready behavior: robust error handling, secure auth, file uploads, and storage-backed downloads.

How this skill works

The skill registers HTTP routes with Convex httpRouter and wraps handlers with httpAction. Handlers can parse JSON, form data, raw bytes, and path parameters, call internal queries and mutations, and use Convex storage for uploads and downloads. It includes helpers for CORS preflight responses, API key and bearer-token validation, and examples of delegating webhook signature verification to internal actions that use provider SDKs (Stripe, GitHub, Svix). Error handling and structured JSON responses are demonstrated for predictable client behavior.

When to use it

• Expose custom API endpoints from a Convex backend (GET, POST, OPTIONS, etc.).
• Receive and validate webhooks from third-party services (Stripe, GitHub, Clerk, Svix).
• Handle file uploads and store blobs in Convex storage, or provide secure file downloads.
• Integrate external APIs and perform server-side mutations/queries securely.
• Implement CORS and preflight handling for browser-based clients.

Best practices

• Always validate Content-Type and parse bodies with try/catch to return informative errors.
• Centralize signature verification in internal actions to keep endpoints lean and testable.
• Return consistent JSON error shapes and appropriate HTTP status codes (400/401/403/500).
• Use pathPrefix for dynamic routes and extract path segments from request.url reliably.
• Attach strict CORS headers only for trusted origins in production; avoid wildcard when possible.

Example use cases

• A Stripe webhook endpoint that verifies signatures and triggers subscription or checkout mutations.
• An authenticated API route that validates API keys or bearer tokens and returns user-specific data.
• A file upload endpoint that stores raw bytes in Convex storage and returns a storageId.
• A webhook receiver for GitHub or Svix that validates the signature and enqueues background processing.
• A public health or status endpoint (GET /health) plus CORS-enabled API routes for a single-page app.