[Convex](https://convex.dev) supports [HTTP actions](https://docs.convex.dev/functions/http-actions), meaning your backend can receive requests not only from Convex clients, such as the [ConvexReactClient](https://docs.convex.dev/using/project-setup#configure-the-convex-client), but also from third-party webhooks and other clients that want to communicate with a custom HTTP API. 

Currently, these endpoints have a simple router. In this post, we’ll look at how to add more advanced features, such as:

- Dynamic routes or slug routes — e.g. `users/:userId`
- Middleware — e.g. check auth on all routes under `/api/*` or implementing CORS
- Helpers for validating an incoming Request’s query params or body
- Helpers for formatting a JSON response or text response
- Custom 404 (Not Found) responses

While it’s possible to build these yourself on top of Convex primitives, existing JS libraries already do a great job at this. In this post, we’re going to go through how you can leverage [Hono](https://hono.dev/) with Convex [HTTP actions](https://docs.convex.dev/functions/http-actions). To use it yourself, you can grab  [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts) in the [convex-helpers repo](https://github.com/get-convex/convex-helpers). We’ll also look more generally at how to extend Convex HTTP endpoint behavior. 

Note: you don’t need to use TypeScript, but I will use it in my examples because both Hono and Convex offer slick TypeScript support! 

# Using Hono with Convex

To use Hono, you’ll need to:

1. `npm install hono` in your project. 
2. Copy [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts) into your `convex/` directory. I like to keep it in `convex/lib/` to separate it from my application logic.
3. In `convex/http.ts`, import `Hono`, `HonoWithConvex`, and `HttpRouterWithHono` and use them like so:

```jsx
import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "./lib/honoWithConvex";

const app: HonoWithConvex = new Hono();

// Add your routes to `app`. See below 

export default new HttpRouterWithHono(app);
```

The `HonoWithConvex` is just a type that tells Hono to expect the Convex [ActionCtx](https://docs.convex.dev/api/interfaces/server.ActionCtx) as its [env](https://hono.dev/api/context#env) binding. `HttpRouterWithHono` does the magic to connect Hono routes to Convex HTTP actions.

Let’s look at a few ways to use Hono:

## Slug routing and response formatting

For illustration, we’ll implement an endpoint from the [Convex demo for HTTP action](https://github.com/get-convex/convex-demos/tree/main/http) to use Hono. Here’s an example handler showcasing several of Hono’s features:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L24
// Routing with slugs
app.get("/listMessages/:userId{[0-9]+}", async (c) => {
  // Extracting a token from the URL!
  const userId = c.req.param("userId");

  // Running a Convex query
  const messages = await c.env.runQuery(api.messages.getByAuthor, { authorNumber: userId });

  // Helpers for pretty JSON!
  c.pretty(true, 2);
  return c.json(messages);
});
```

…and an example response:

```bash
$ curl https://happy-animal-123.convex.site/listMessages/123
[
  {
    "_creationTime": 1677798437141.091,
    "_id": {
      "$id": "messages|lqMHm5kDS9m6fBsSnx5L2g"
    },
    "author": "User 123",
    "body": "Hello world"
  },
]
```

## Input validation

Here’s another handler with input validation:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L36
app.post(
  "/postMessage",
  // Body validation!
  zValidator(
    "json",
    z.object({
      author: z.string().startsWith("User "),
      body: z.string().max(100),
    })
  ),
  async (c) => {
    // With type safety!
    const { body, author } = c.req.valid("json");
await c.env.runMutation(api.messages.send, { body, author });
    return c.text("Sent message!");
  }
);
```

…and an example response:

```bash
$ curl -d '{ "body": "Hello world", "author": "123" }'  https://happy-animal-123.convex.site/postMessage
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_string",
        "validation": {
          "startsWith": "User "
        },
        "message": "Invalid input: must start with \"User \"",
        "path": [
          "author"
        ]
      }
    ],
    "name": "ZodError"
  }
}
```

## Middleware: Adding CORS

Another example, copying from [Hono docs](https://hono.dev/middleware/builtin/cors). This adds CORS support to the `/api/*` and `/api2/*` routes with different configurations.

```typescript
import { cors } from 'hono/cors'
...
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L55
app.use('/api/*', cors())

app.use(
  '/api2/*',
  cors({
    origin: 'http://examplesite.com',
    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
    allowMethods: ['POST', 'GET', 'OPTIONS'],
    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
    maxAge: 600,
    credentials: true,
  })
)
```

The `.use` function registers a handler for all `/api/*` requests. As we’ll see below, you can use this for a variety of situations, including logging.

## Custom 404 responses

To set up a custom 404, we can do:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L12
// Custom 404
app.notFound(c => {
  return c.text("Oh no! Couldn't find a route for that", 404);
});
```

See [https://hono.dev/](https://hono.dev/) for more features.

<BuildWithConvex />

# Under the hood

Curious about how to extend Convex [HTTP actions](https://docs.convex.dev/functions/http-actions) for your own purposes? Read on!

## Extending routes using the `/` prefix

If the routing options aren’t flexible enough for your use case, you can handle all HTTP requests with a single `httpAction` and do complex routing there. For instance, instead of using `HttpRouterWithHono`, we could define a single route per HTTP method in `convex/http.ts`:

```typescript
import { httpRouter, ROUTABLE_HTTP_METHODS } from "convex/server";
import { httpAction } from "./_generated/server";
import { HonoWithConvex } from "./lib/honoWithConvex";

const app: HonoWithConvex = new Hono();

// Add your routes to `app`.

const http = httpRouter();
for (const routableMethod of ROUTABLE_HTTP_METHODS) {
	http.route({
		pathPrefix: "/",
		method: routableMethod,
		handler: httpAction(async (ctx, request: Request) => {
			return await app.fetch(request, ctx);
		}),
	})
}
export default http;
```

We could stop here — we can now use Hono and Convex together! But we could make a couple of additional improvements to leverage the [Convex dashboard](https://dashboard.convex.dev/).

## Using middleware to add per-route logging

Here’s what we see in the [Convex dashboard](https://dashboard.convex.dev/) under “Logs” given the approach of registering an `httpAction` per method:

![Logs showing GET /*](https://cdn.sanity.io/images/ts10onj4/production/06c3e0c48a26da60a29a095e5c6f5e184d6ae2b0-1302x310.png?w=700)

All our GET requests will appear as `GET /*` even when we have multiple routes.

We can pretty easily get a little more information using one of Hono’s features — logging middleware:

```typescript
import { logger } from "hono/logger";
import stripAnsi from "strip-ansi";

app.use(
  "*",
  logger((...args) => {
    console.log(...args.map(stripAnsi));
  })
);
```

Now the [Convex dashboard](https://dashboard.convex.dev/) looks more like this:

![Logs with GET /listMessages/123](https://cdn.sanity.io/images/ts10onj4/production/e1ff98ab9fdcc7e5eee3b741eca5025b98c762e9-1350x524.png?w=700)

Note: these say `0ms` because they’re running in [Convex’s deterministic environment that provides a different `Date.now()`](https://docs.convex.dev/understanding/convex-fundamentals/functions#determinism).

## Subclassing `HttpRouter` (the `HttpRouterWithHono` approach)

If we want the fullest integration with the [Convex dashboard](https://dashboard.convex.dev/), we’d like to see something like this under “Logs”, where we show the routed path:

![Logs showing GET /listMessages/:userId](https://cdn.sanity.io/images/ts10onj4/production/212100c96760c3d1b86ec79a59ce3d5246a60ca3-1526x514.png?w=700)

And then see a corresponding entry with metrics under the “Functions” tab:

![Functions metrics for GET /listMesssages/:userId](https://cdn.sanity.io/images/ts10onj4/production/9527a4a514b8fb6aa98023e27da58b90fbdede3b-970x922.png?w=450)

The code needed for this behavior is in  [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts).

**How does it work?**

`HttpRouterWithHono` is a subclass of the Convex [`HttpRouter`](https://docs.convex.dev/api/classes/server.HttpRouter) which overrides two special methods:

- `getRoutes` returns a list of `[path, method, handler]`, which we use to populate the Functions page on the dashboard.
- `lookup(path, method)` returns `[handler, path, method]`. Convex will run `handler` when responding to the request and use the `path` and `method` for metrics and logging (so this should match a path + method combo from `getRoutes`)
    - As an example, I wanted `lookup("/listMessages/123", "GET")` to return `"/listMessages/:userId{[0-9]+}"` for the path and `"GET"` for the method.

The implementation I added is not optimal (it loops through all the routes), but it still works! The Convex router is very flexible, so there are many options for configuring how your HTTP actions get routed and show up in the dashboard. 

Now, we can use Convex with Hono and take advantage of most of the features provided in the Convex dashboard!

# Summary

In this post, we looked at how to use Hono with Convex, including how to extend Convex’s HTTP actions to add your own functionality. Let us know what you think in [our discord](https://convex.dev/community) and if you end up using Hono and Convex together! ❤️

Adding advanced HTTP Endpoint functionality by extending Convex with Hono.

Advanced HTTP Endpoints: Convex ❤️ Hono

Convex provides [client libraries](https://docs.convex.dev/tutorial/how-it-works#the-convex-client) for storing and interacting with data, but sometimes we want a third-party app like Discord to interact with data in Convex. This is often done via a webhook over HTTP, which Convex recently [added support for](https://docs.convex.dev/using/http-endpoints)! I used this functionality to build a simple Discord bot that posts custom responses to certain key phrases.

I store my prompts and responses using Convex, and can edit them from a web app using the [`ConvexReactClient`](https://docs.convex.dev/get-started#the-convex-client) (shown in orange). When I trigger my Discord bot, Discord sends an HTTP request via a webhook to a configured URL (my Convex deployment), which I handle using an [`httpAction`](https://docs.convex.dev/functions/http-actions) (shown in blue).

![Diagram](https://cdn.sanity.io/images/ts10onj4/production/053eef3b2604f3af0b868e46ed9ada978dd39683-1804x1320.png?w=900)


The full code for my app is in [https://github.com/sshader/discord-bot](https://github.com/sshader/discord-bot), but I'll focus on the webhook specifically.

After setting up my Discord bot and registering a command, I now needed to figure out how to respond to the webhook requests. I can define an endpoint that just returns a successful response to test that everything is hooked up correctly:

```typescript
// https://github.com/sshader/discord-bot/blob/stack/convex/http.ts#L9
const http = httpRouter();
http.route({
  path: '/discord',
  method: 'POST',
  handler: httpAction(async ({}, request) => {
    return new Response(null, { status: 200 })
  })
});
```

When I try updating my Discord bot settings, I can see in the Convex dashboard that my endpoint is getting run.

![Screenshot](https://cdn.sanity.io/images/ts10onj4/production/273a5f3f5e093082998c0677d0e99d05eb195e2f-387x117.png?w=900)

![Screenshot](https://cdn.sanity.io/images/ts10onj4/production/1b09cf5bb7792d01e91dc2cec734ad0ae1b44a89-702x137.png?w=900)

[Discord requires](https://discord.com/developers/docs/interactions/receiving-and-responding#receiving-an-interaction) that you (1) acknowledge a “ping” request and (2) verify the signature of the request and reject it if it’s invalid before it will send your endpoint any webhook events. I used the [discord-interactions](https://www.npmjs.com/package/discord-interactions) npm package to verify the signature.

```typescript
// https://github.com/sshader/discord-bot/blob/stack/convex/http.ts#L14
httpAction(async ({}, request) => {
  const bodyText = await request.text();

  // Check signature -- uses discord-interactions package
  const isValidSignature = verifyKey(
    bodyText,
    request.headers.get('X-Signature-Ed25519'),
    request.headers.get('X-Signature-Timestamp'),
    process.env.DISCORD_PUBLIC_KEY
  )
  if (!isValidSignature) {
    return new Response("invalid request signature", { status: 401 });
  }
	
  const body = JSON.parse(bodyText);
  // Handle ping
  if (body.type === InteractionType.PING) {
    return new Response(
      JSON.stringify({ type: InteractionResponseType.PONG }),
      { status: 200 }
    )
  }
});
```

In addition to the [Convex docs](https://docs.convex.dev/functions/http-actions) it was helpful to look at [Cloudflare workers](https://developers.cloudflare.com/workers/examples/return-json/), which have similar JS handlers using the [fetch standard](https://fetch.spec.whatwg.org/). Viewing my endpoint logs in the dashboard helped me catch an issue where I initially did these steps in the reverse order, and so wasn’t verifying signatures on the “ping” requests.

The last part is to query my Convex data and respond to Discord -- I have a Convex query that returns a stores response for a given prompt which I'm using here:
```typescript
// https://github.com/sshader/discord-bot/blob/stack/convex/http.ts#L37
const data = body.data;
if (
  body.type === InteractionType.APPLICATION_COMMAND &&
  data.name === "ask_convex"
) {
  const prompt = data.options[0].value;
  // See https://github.com/sshader/discord-bot/blob/stack/convex/botResponses.ts#L2
  const botResponse = await runQuery("bot_responses:getBotResponse", { prompt });

  return new Response(
    JSON.stringify({
      type: InteractionResponseType.CHANNEL_MESSAGE_WITH_SOURCE,
      data: { content: botResponse },
    }),
    { headers: { "content-type": "application/json" }, status: 200 }
  );
} 
```

Here’s how it looks all together!

![Screenshot of the final app](https://cdn.sanity.io/images/ts10onj4/production/c9f5fcf5d06fa2c077dcdec18d8cad8b5df5b605-600x338.gif)



Convex provides client libraries for storing and interacting with data, but sometimes we want a third-party app like Discord to interact with data in Convex. In this post, we use webhooks to build a simple Discord bot powered by Convex.

Sarah Shader

All posts by Sarah