Convex http actions

--- name: convex-http-actions displayName: Convex HTTP Actions description: External API integration and webhook handling including HTTP endpoint routing, request/response handling, authentication, CORS configuration, and webhook signature validation version: 1.0.0 author: Convex tags: [convex, http, actions, webhooks, api, endpoints] --- # Convex HTTP Actions Build HTTP endpoints for webhooks, external API integrations, and custom routes in Convex applications. ## Documentation Sources Before implementing, do not assume; fetch the latest documentation: - Primary: https://docs.convex.dev/functions/http-actions - Actions Overview: https://docs.convex.dev/functions/actions - Authentication: https://docs.convex.dev/auth - For broader context: https://docs.convex.dev/llms.txt ## Instructions ### HTTP Actions Overview HTTP actions allow you to define HTTP endpoints in Convex that can: - Receive webhooks from third-party services - Create custom API routes - Handle file uploads - Integrate with external services - Serve dynamic content ### Basic HTTP Router Setup ``typescript // convex/http.ts import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); // Simple GET endpoint http.route({ path: "/health", method: "GET", handler: httpAction(async (ctx, request) => { return new Response(JSON.stringify({ status: "ok" }), { status: 200, headers: { "Content-Type": "application/json" }, }); }), }); export default http; ` ### Request Handling `typescript // convex/http.ts import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); // Handle JSON body http.route({ path: "/api/data", method: "POST", handler: httpAction(async (ctx, request) => { // Parse JSON body const body = await request.json(); // Access headers const authHeader = request.headers.get("Authorization"); // Access URL parameters const url = new URL(request.url); const queryParam = url.searchParams.get("filter"); return new Response( JSON.stringify({ received: body, filter: queryParam }), { status: 200, headers: { "Content-Type": "application/json" }, } ); }), }); // Handle form data http.route({ path: "/api/form", method: "POST", handler: httpAction(async (ctx, request) => { const formData = await request.formData(); const name = formData.get("name"); const email = formData.get("email"); return new Response( JSON.stringify({ name, email }), { status: 200, headers: { "Content-Type": "application/json" }, } ); }), }); // Handle raw bytes http.route({ path: "/api/upload", method: "POST", handler: httpAction(async (ctx, request) => { const bytes = await request.bytes(); const contentType = request.headers.get("Content-Type") ?? "application/octet-stream"; // Store in Convex storage const blob = new Blob([bytes], { type: contentType }); const storageId = await ctx.storage.store(blob); return new Response( JSON.stringify({ storageId }), { status: 200, headers: { "Content-Type": "application/json" }, } ); }), }); export default http; ` ### Path Parameters Use path prefix matching for dynamic routes: `typescript // convex/http.ts import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); // Match /api/users/* with pathPrefix http.route({ pathPrefix: "/api/users/", method: "GET", handler: httpAction(async (ctx, request) => { const url = new URL(request.url); // Extract user ID from path: /api/users/123 -> "123" const userId = url.pathname.replace("/api/users/", ""); return new Response( JSON.stringify({ userId }), { status: 200, headers: { "Content-Type": "application/json" }, } ); }), }); export default http; ` ### CORS Configuration ``typescript // convex/http.ts import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); // CORS headers helper const corsHeaders = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS", "Access-Control-Allow-Headers": "Content-Type, Authorization", "Access-Control-Max-Age": "86400", }; // Handle preflight requests http.route({ path: "/api/data", method: "OPTIONS", handler: httpAction(async () => { return new Response(null, { status: 204, headers: corsHeaders, }); }), }); // Actual endpoint with CORS http.route({ path: "/api/data", method: "POST", handler: httpAction(async (ctx, request) => { const body = await request.json(); return new Response( JSON.stringify({ success: true, data: body }), { status: 200,