convex-http-actions

Name: convex-http-actions
Author: waynesutton

109installs31forks

How to install convex-http-actions?

waynesutton/convexskills/convex-http-actions

$npx -y skills add waynesutton/convexskills --skill convex-http-actions

Installs into the current project.

Summary

External API integration and webhook handling including HTTP endpoint routing, request/response handling, authentication, CORS configuration, and webhook signature validation

Files · 1

View on GitHub

SKILL.md

1	# Convex HTTP Actions
2
3	Build HTTP endpoints for webhooks, external API integrations, and custom routes in Convex applications.
4
5	## Documentation Sources
6
7	Before implementing, do not assume; fetch the latest documentation:
8
9	- Primary: https://docs.convex.dev/functions/http-actions
10	- Actions Overview: https://docs.convex.dev/functions/actions
11	- Authentication: https://docs.convex.dev/auth
12	- For broader context: https://docs.convex.dev/llms.txt
13
14	## Instructions
15
16	### HTTP Actions Overview
17
18	HTTP actions allow you to define HTTP endpoints in Convex that can:
19
20	- Receive webhooks from third-party services
21	- Create custom API routes
22	- Handle file uploads
23	- Integrate with external services
24	- Serve dynamic content
25
26	### Basic HTTP Router Setup
27
28	```typescript
29	// convex/http.ts
30	import { httpRouter } from "convex/server";
31	import { httpAction } from "./_generated/server";
32
33	const http = httpRouter();
34
35	// Simple GET endpoint
36	http.route({
37	path: "/health",
38	method: "GET",
39	handler: httpAction(async (ctx, request) => {
40	return new Response(JSON.stringify({ status: "ok" }), {
41	status: 200,
42	headers: { "Content-Type": "application/json" },
43	});
44	}),
45	});
46
47	export default http;
48	```
49
50	### Request Handling
51
52	```typescript
53	// convex/http.ts
54	import { httpRouter } from "convex/server";
55	import { httpAction } from "./_generated/server";
56
57	const http = httpRouter();
58
59	// Handle JSON body
60	http.route({
61	path: "/api/data",
62	method: "POST",
63	handler: httpAction(async (ctx, request) => {
64	// Parse JSON body
65	const body = await request.json();
66
67	// Access headers
68	const authHeader = request.headers.get("Authorization");
69
70	// Access URL parameters
71	const url = new URL(request.url);
72	const queryParam = url.searchParams.get("filter");
73
74	return new Response(
75	JSON.stringify({ received: body, filter: queryParam }),
76	{
77	status: 200,
78	headers: { "Content-Type": "application/json" },
79	}
80	);
81	}),
82	});
83
84	// Handle form data
85	http.route({
86	path: "/api/form",
87	method: "POST",
88	handler: httpAction(async (ctx, request) => {
89	const formData = await request.formData();
90	const name = formData.get("name");
91	const email = formData.get("email");
92
93	return new Response(
94	JSON.stringify({ name, email }),
95	{
96	status: 200,
97	headers: { "Content-Type": "application/json" },
98	}
99	);
100	}),
101	});
102
103	// Handle raw bytes
104	http.route({
105	path: "/api/upload",
106	method: "POST",
107	handler: httpAction(async (ctx, request) => {
108	const bytes = await request.bytes();
109	const contentType = request.headers.get("Content-Type") ?? "application/octet-stream";
110
111	// Store in Convex storage
112	const blob = new Blob([bytes], { type: contentType });
113	const storageId = await ctx.storage.store(blob);
114
115	return new Response(
116	JSON.stringify({ storageId }),
117	{
118	status: 200,
119	headers: { "Content-Type": "application/json" },
120	}
121	);
122	}),
123	});
124
125	export default http;
126	```
127
128	### Path Parameters
129
130	Use path prefix matching for dynamic routes:
131
132	```typescript
133	// convex/http.ts
134	import { httpRouter } from "convex/server";
135	import { httpAction } from "./_generated/server";
136
137	const http = httpRouter();
138
139	// Match /api/users/* with pathPrefix
140	http.route({
141	pathPrefix: "/api/users/",
142	method: "GET",
143	handler: httpAction(async (ctx, request) => {
144	const url = new URL(request.url);
145	// Extract user ID from path: /api/users/123 -> "123"
146	const userId = url.pathname.replace("/api/users/", "");
147
148	return new Response(
149	JSON.stringify({ userId }),
150	{
151	status: 200,
152	headers: { "Content-Type": "application/json" },
153	}
154	);
155	}),
156	});
157
158	export default http;
159	```
160
161	### CORS Configuration
162
163	```typescript
164	// convex/http.ts
165	import { httpRouter } from "convex/server";
166	import { httpAction } from "./_generated/server";
167
168	const http = httpRouter();
169
170	// CORS headers helper
171	const corsHeaders = {
172	"Access-Control-Allow-Origin": "*",
173	"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
174	"Access-Control-Allow-Headers": "Content-Type, Authorization",
175	"Access-Control-Max-Age": "86400",
176	};
177
178	// Handle preflight requests
179	http.route({
180	path: "/api/data",
181	method: "OPTIONS",
182	handler: httpAction(async () => {
183	return new Response(null, {
184	status: 204,
185	headers: corsHeaders,
186	});
187	}),
188	});
189
190	// Actual endpoint with CORS
191	http.route({
192	path: "/api/data",
193	method: "POST",
194	handler: httpAction(async (ctx, request) => {
195	const body = await request.json();
196
197	return new Response(
198	JSON.stringify({ success: true, data: body }),
199	{
200	status: 200,

People who liked this also viewed

6 picks

Type

convex-http-actions

109installs31forks

View on GitHub

How to install convex-http-actions?

waynesutton/convexskills/convex-http-actions

$npx -y skills add waynesutton/convexskills --skill convex-http-actions

Installs into the current project.

Summary

External API integration and webhook handling including HTTP endpoint routing, request/response handling, authentication, CORS configuration, and webhook signature validation

Files · 1

View on GitHub

SKILL.md

1	# Convex HTTP Actions
2
3	Build HTTP endpoints for webhooks, external API integrations, and custom routes in Convex applications.
4
5	## Documentation Sources
6
7	Before implementing, do not assume; fetch the latest documentation:
8
9	- Primary: https://docs.convex.dev/functions/http-actions
10	- Actions Overview: https://docs.convex.dev/functions/actions
11	- Authentication: https://docs.convex.dev/auth
12	- For broader context: https://docs.convex.dev/llms.txt
13
14	## Instructions
15
16	### HTTP Actions Overview
17
18	HTTP actions allow you to define HTTP endpoints in Convex that can:
19
20	- Receive webhooks from third-party services
21	- Create custom API routes
22	- Handle file uploads
23	- Integrate with external services
24	- Serve dynamic content
25
26	### Basic HTTP Router Setup
27
28	```typescript
29	// convex/http.ts
30	import { httpRouter } from "convex/server";
31	import { httpAction } from "./_generated/server";
32
33	const http = httpRouter();
34
35	// Simple GET endpoint
36	http.route({
37	path: "/health",
38	method: "GET",
39	handler: httpAction(async (ctx, request) => {
40	return new Response(JSON.stringify({ status: "ok" }), {
41	status: 200,
42	headers: { "Content-Type": "application/json" },
43	});
44	}),
45	});
46
47	export default http;
48	```
49
50	### Request Handling
51
52	```typescript
53	// convex/http.ts
54	import { httpRouter } from "convex/server";
55	import { httpAction } from "./_generated/server";
56
57	const http = httpRouter();
58
59	// Handle JSON body
60	http.route({
61	path: "/api/data",
62	method: "POST",
63	handler: httpAction(async (ctx, request) => {
64	// Parse JSON body
65	const body = await request.json();
66
67	// Access headers
68	const authHeader = request.headers.get("Authorization");
69
70	// Access URL parameters
71	const url = new URL(request.url);
72	const queryParam = url.searchParams.get("filter");
73
74	return new Response(
75	JSON.stringify({ received: body, filter: queryParam }),
76	{
77	status: 200,
78	headers: { "Content-Type": "application/json" },
79	}
80	);
81	}),
82	});
83
84	// Handle form data
85	http.route({
86	path: "/api/form",
87	method: "POST",
88	handler: httpAction(async (ctx, request) => {
89	const formData = await request.formData();
90	const name = formData.get("name");
91	const email = formData.get("email");
92
93	return new Response(
94	JSON.stringify({ name, email }),
95	{
96	status: 200,
97	headers: { "Content-Type": "application/json" },
98	}
99	);
100	}),
101	});
102
103	// Handle raw bytes
104	http.route({
105	path: "/api/upload",
106	method: "POST",
107	handler: httpAction(async (ctx, request) => {
108	const bytes = await request.bytes();
109	const contentType = request.headers.get("Content-Type") ?? "application/octet-stream";
110
111	// Store in Convex storage
112	const blob = new Blob([bytes], { type: contentType });
113	const storageId = await ctx.storage.store(blob);
114
115	return new Response(
116	JSON.stringify({ storageId }),
117	{
118	status: 200,
119	headers: { "Content-Type": "application/json" },
120	}
121	);
122	}),
123	});
124
125	export default http;
126	```
127
128	### Path Parameters
129
130	Use path prefix matching for dynamic routes:
131
132	```typescript
133	// convex/http.ts
134	import { httpRouter } from "convex/server";
135	import { httpAction } from "./_generated/server";
136
137	const http = httpRouter();
138
139	// Match /api/users/* with pathPrefix
140	http.route({
141	pathPrefix: "/api/users/",
142	method: "GET",
143	handler: httpAction(async (ctx, request) => {
144	const url = new URL(request.url);
145	// Extract user ID from path: /api/users/123 -> "123"
146	const userId = url.pathname.replace("/api/users/", "");
147
148	return new Response(
149	JSON.stringify({ userId }),
150	{
151	status: 200,
152	headers: { "Content-Type": "application/json" },
153	}
154	);
155	}),
156	});
157
158	export default http;
159	```
160
161	### CORS Configuration
162
163	```typescript
164	// convex/http.ts
165	import { httpRouter } from "convex/server";
166	import { httpAction } from "./_generated/server";
167
168	const http = httpRouter();
169
170	// CORS headers helper
171	const corsHeaders = {
172	"Access-Control-Allow-Origin": "*",
173	"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
174	"Access-Control-Allow-Headers": "Content-Type, Authorization",
175	"Access-Control-Max-Age": "86400",
176	};
177
178	// Handle preflight requests
179	http.route({
180	path: "/api/data",
181	method: "OPTIONS",
182	handler: httpAction(async () => {
183	return new Response(null, {
184	status: 204,
185	headers: corsHeaders,
186	});
187	}),
188	});
189
190	// Actual endpoint with CORS
191	http.route({
192	path: "/api/data",
193	method: "POST",
194	handler: httpAction(async (ctx, request) => {
195	const body = await request.json();
196
197	return new Response(
198	JSON.stringify({ success: true, data: body }),
199	{
200	status: 200,

People who liked this also viewed

6 picks

Type