#Convex HTTP + Hono

9 messages · Page 1 of 1 (latest)

spice thicket
fleet talonBOT
#

Hi @spice thicket. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To implement a POST endpoint using Convex and Hono that handles the request structure you've provided, you can follow these steps.

1. Project Setup

Ensure you have the necessary packages installed in your project:

npm install hono convex-helpers

[Using Hono with Convex]

2. Implementation with Hono

You can define your route in convex/http.ts. To handle the specific POST request and extract the JSON body, your code should look like this:

import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";
import { ActionCtx } from "./_generated/server";
import { api } from "./_generated/api";

const app: HonoWithConvex<ActionCtx> = new Hono();

// Match the path: /api/workflows/google-search-keywords
app.post("/api/workflows/google-search-keywords", async (c) => {
  // 1. Authenticate the request
  const authHeader = c.req.header("Authorization");
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  // 2. Parse the JSON body
  const body = await c.req.json();
  const { searchQuery, searchLocation, maxResults, strictness } = body;

  // 3. Execute Convex logic (e.g., running an action or mutation)
  // Access Convex context via c.env
  await c.env.runAction(api.myActions.processSearch, {
    query: searchQuery,
    location: searchLocation,
    limit: maxResults,
  });

  return c.json({ status: "success" });
});

export default new HttpRouterWithHono(app);

[Using Hono with Convex; Input validation]

Important Considerations

#
  • Endpoint URL: Your curl command uses .convex.cloud. While the Convex HTTP API (for calling internal functions directly) uses .convex.cloud, custom HTTP actions defined via the httpRouter (including Hono-wrapped ones) are exposed on your .convex.site URL [Defining HTTP actions]. For the code above, the URL would be:
    <https://clever-grouse-738.convex.site/api/workflows/google-search-keywords>
  • Authentication: If you are using Convex's built-in auth (like Clerk or Auth0), the Bearer token will be automatically processed, and you can access the user identity via c.env.auth.getUserIdentity() [Authenticate HTTP actions]. If you are using a custom API key, you should manually verify the header as shown in the code above [Discord support thread].
  • Timeout: Your curl command specifies --max-time 10. Note that Convex HTTP actions have their own execution limits, but standard Fetch API responses are expected [Functions API].
  • CORS: If you plan to call this from a browser, you must add Hono's CORS middleware to your app [Adding CORS].

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@spice thicket Kapa.ai is still learning and improving, please let me know how I did by reacting below.

spice thicket
#

@fleet talon This here returns this it states `

  • [HTTP/2] [1] OPENED stream for https://clever-grouse-738.convex.cloud/api/workflows/google-search-keywords
  • [HTTP/2] [1] [:method: POST]
  • [HTTP/2] [1] [:scheme: https]
  • [HTTP/2] [1] [:authority: clever-grouse-738.convex.cloud]
  • [HTTP/2] [1] [:path: /api/workflows/google-search-keywords]
  • [HTTP/2] [1] [user-agent: curl/8.5.0]
  • [HTTP/2] [1] [accept: /]
  • [HTTP/2] [1] [authorization: Bearer CrPchfJZPMA6UBsaxy8arLdbdLKTR5zWR1mhUdwnbYbc]
  • [HTTP/2] [1] [content-type: application/json]
  • [HTTP/2] [1] [content-length: 140]

POST /api/workflows/google-search-keywords HTTP/2
Host: clever-grouse-738.convex.cloud
User-Agent: curl/8.5.0
Accept: /
Authorization: Bearer *****************
Content-Type: application/json
Content-Length: 140

< HTTP/2 404
< access-control-allow-credentials: true
< date: Tue, 13 Jan 2026 01:44:26 GMT
< vary: origin, access-control-request-method, access-control-request-headers
< via: 1.1 Caddy
< x-convex-usher: 1
< x-robots-tag: noindex, nofollow
< content-length: 0
<

  • Connection #0 to host clever-grouse-738.convex.cloud left intact
    bozo@MSI:~/projects/business/CbamReady$ `

So I went and I set it up in http.ts like this here `

fleet talonBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

I'm sorry, but it appears your question was cut off before you could provide the code from your http.ts file. However, based on the curl output provided, there is a clear reason why you are receiving a 404 Not Found error.

The primary issue is the URL hostname you are using.

Use .convex.site instead of .convex.cloud

In your curl command, you are hitting:
<https://clever-grouse-738.convex.cloud/api/workflows/google-search-keywords>

In Convex, the .convex.cloud domain is reserved for the system's built-in Functions API (like /api/query or /api/mutation). Custom HTTP actions and routes defined in your convex/http.ts file are exposed on a different domain ending in .convex.site.

To resolve the 404, change your request to:
<https://clever-grouse-738.convex.site/api/workflows/google-search-keywords>

[Defining HTTP actions; Debugging HTTP Actions]

Additional Troubleshooting Steps

If changing the URL does not fix the issue, please check the following:

#
  1. Deployment Success: Ensure your latest code has been successfully pushed. Check the Functions page in your Convex dashboard to confirm that an entry named http exists. If it doesn't, your http.ts file may have a syntax error or is not named exactly http.ts (or http.js) in the convex/ folder. [Debugging HTTP Actions]
  2. Route Registration: If you are using Hono or the standard httpRouter, ensure you have a default export of the router at the end of your file. Convex specifically expects the router to be the default export to register the routes. [Defining HTTP actions]
  3. Path Matching: Ensure the path in your code exactly matches /api/workflows/google-search-keywords. If you are using Hono, remember that a trailing slash (or lack thereof) can sometimes cause a mismatch depending on your configuration. [Using Hono with Convex]

If you can provide the content of your http.ts file, I can give you more specific feedback on the implementation.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: