# Guide to Convex Webhooks: Features and Best Practices

Convex is a backend platform where you write queries, mutations and actions in TypeScript and the database keeps clients in sync in real time. It doesn't send business-event webhooks the way a payments API does, because your own Convex functions already react to changes in your data. What it does send is telemetry. A **webhook log stream** posts batches of a deployment's logs to a URL you choose: every function execution with its timing and outcome, `console` output, changes from the audit log, and periodic concurrency, scheduler and storage statistics. Teams use it to feed their own logging or alerting pipeline when Convex's built-in Axiom, Datadog and PostHog integrations don't fit.

This guide covers how the webhook log stream is set up, what the batched body looks like, how to verify its `sha256=` signature, and what Convex's best-effort delivery means for anything you build on it.

## What are Convex webhooks?

Log streams are a Pro plan feature, configured per deployment. The webhook option is the generic one: its only setting is the URL. Once it is saved, Convex buffers log events in memory and sends them in batches as `POST` requests. Each body is a JSON array, and each element is one log event with a `topic`, a `timestamp` in Unix milliseconds and a `convex` object describing the deployment.

Every request is signed. `x-webhook-signature` carries `sha256=` followed by a hex HMAC-SHA256 of the raw body, keyed with an HMAC secret the dashboard shows when you configure the stream.

## Convex webhook features

| Feature | Details |
| --- | --- |
| Availability | Pro plan |
| Configuration | Deployment Settings > **Integrations** > **Webhook** |
| Subscription | None. Every topic is sent |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-webhook-signature`, as `sha256=<hex>` |
| Signed content | The raw request body, covering the whole batch |
| Secret | Generated by Convex and shown in the dashboard, one per stream |
| Body | JSON |
| Event routing | Body field `[].topic` |
| Delivery | Best effort, batched. Events can be dropped under load or duplicated |
| Retries, timeout, IPs | Not documented |

## Events and payloads

| Topic | Triggered When | Key fields |
| --- | --- | --- |
| `verification` | The stream is created, to confirm it works | `message` |
| `console` | A function calls the `console` API | `function`, `log_level` (`DEBUG`/`INFO`/`LOG`/`WARN`/`ERROR`), `message`, `is_truncated` |
| `function_execution` | Any function runs | `function`, `execution_time_ms`, `status` (`success`/`failure`), `error_message`, `usage` |
| `audit_log` | A deployment change (also in the dashboard History tab) | `audit_log_action`, `audit_log_metadata` (stringified JSON) |
| `concurrency_stats` | Once a minute, when stats changed | `query`, `mutation`, `action`, `node_action`, `http_action` (`num_running`, `num_queued`) |
| `scheduler_stats` | Periodically from the scheduler | `lag_seconds`, `num_running_jobs` |
| `current_storage_usage` | Periodically | `total_document_size_bytes`, `total_index_size_bytes`, `total_file_storage_bytes`, ... |
| `storage_api_bandwidth` | A client downloads a file from the storage HTTP API | `storage_id`, `egress_bytes` |
| `ai_gateway_usage` | An AI Gateway inference ends | `inference_id`, `provider`, `model`, `cost`, `outcome` |

`function` (on `console` and `function_execution`) has `type` (`query`, `mutation`, `action`, `http_action`), `path` (for example `messages:send`), `request_id` and optionally `cached`.

A single delivery usually mixes topics: a burst of `function_execution` events, a few `console` lines from the same requests, and maybe a `concurrency_stats` snapshot. Use `function.request_id` to join a function's console output to its execution record. `audit_log_metadata` is a JSON string inside the JSON, so parse it a second time.

Streams configured before 23 May 2024 use a legacy event format, and nothing in a delivery says which format it is. Recreate an old stream to get the format above. Convex's sample handler also mentions a JSONL variant that the page doesn't otherwise describe, so check the first byte of the body if you aren't sure.

## Setting up Convex webhooks

1. Open the [Deployment Settings](https://dashboard.convex.dev/deployment/settings) of the deployment in the Convex dashboard and select the **Integrations** tab.
2. Choose the **Webhook** card.
3. Enter your endpoint URL. It is the only setting.
4. Copy the **HMAC secret** the dashboard shows and store it as `WEBHOOK_SECRET`.

Convex then starts streaming, beginning with a `verification` event. To stop, delete the integration from its card menu.

Log streams belong to a deployment, so your dev and prod deployments each need their own webhook and each has its own secret. Point them at different sources or paths so dev logs don't mix with production.

To see the stream on your machine first, forward it with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 convex --path /webhooks/convex

```

## Securing Convex webhooks

Strip `sha256=` from `x-webhook-signature`, compute an HMAC-SHA256 of the raw body with the secret's UTF-8 bytes, encode it as hex and compare in constant time. Convex's own sample does the same with `crypto.subtle.verify` over the request's `arrayBuffer()`. See the [verification documentation](https://docs.convex.dev/production/integrations/log-streams#securing-webhook-log-streams).

```javascript
const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-webhook-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler verifies the whole batch once, then splits it into events and sends each to your log store. It skips `verification` events and raises an alert for failed function executions.

```javascript
const express = require('express');

function createConvexLogApp({ writeLogs, alert }) {
  const app = express();
  app.post('/webhooks/convex', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    let batch;
    try {
      batch = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.sendStatus(400);
    }
    const items = Array.isArray(batch) ? batch : [batch];
    if (!items.length || items.some((e) => !e || typeof e !== 'object' || typeof e.topic !== 'string')) {
      return res.sendStatus(400);
    }
    const logEvents = items.filter((e) => e.topic !== 'verification');
    try {
      await writeLogs(logEvents);
      for (const e of logEvents) {
        if (e.topic === 'function_execution' && e.status === 'failure') {
          await alert(e.function?.path, e.error_message, e.function?.request_id);
        }
      }
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

No timestamp is signed separately; each event's `timestamp` sits inside the signed body. Convex's sample optionally rejects a batch whose first event is more than 5 minutes old. Batches can be delayed and retried, so treat that check as optional and deduplicate instead.

Hookdeck's Convex source type reads the `sha256=` value and verifies it as a hex HMAC-SHA256 of the raw body with your HMAC secret. Hookdeck answers Convex with `200` either way, records a failed check as failed verification, and doesn't deliver that request. It never compares event timestamps with the current time.

> **Make Convex log streams production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies each Convex batch, stores it, and delivers it to your logging pipeline with retries, so an outage in your collector doesn't add to the events Convex already drops under load.

## Convex webhook limitations and pain points

### Best effort means gaps

**The Problem:** Your function execution counts don't match Convex's dashboard, and some errors never reach your alerting.

**Why It Happens:** Convex buffers log events in memory and sends them in batches. Its docs say events can be dropped under high throughput. There's no documented retry schedule or redelivery.

**Workarounds:**

* Use the log stream for observability and alerting, not as a source of truth for billing or business logic.
* Alert on trends, such as error rates, rather than on every single event.
* Write anything you must not lose to a Convex table from inside your functions.

**How Hookdeck Can Help:** Hookdeck accepts each batch as soon as it arrives and stores it, so once Convex has sent it, a slow or unavailable collector on your side doesn't lose it.

### Duplicates without an event ID

**The Problem:** Error counts are inflated after network trouble.

**Why It Happens:** Convex warns that network retries can duplicate log events. Events have no unique event ID to deduplicate on.

**Workarounds:**

* Build a key from `topic`, `timestamp` and `function.request_id` where present.
* Deduplicate in your log store if it supports it.

**How Hookdeck Can Help:** Hookdeck's deduplication can drop byte-identical batches before they reach your collector.

### No filtering

**The Problem:** Your endpoint receives every topic, including high-volume `function_execution` events you may not need.

**Why It Happens:** The webhook stream has one setting, the URL. There is no topic selection.

**Workarounds:**

* Filter by `topic` in your handler and drop what you don't store.
* Size the endpoint for your busiest deployment's full log volume.

**How Hookdeck Can Help:** Hookdeck transformations can drop topics you don't want from each batch before it reaches your service, and filters can route batches by content.

### Two formats, unlabelled

**The Problem:** A parser written for the current format breaks on an older stream.

**Why It Happens:** Streams created before 23 May 2024 send a legacy format, and deliveries don't say which format they use.

**Workarounds:**

* Recreate older streams so every deployment sends the current format.
* Validate the shape of each event and log anything unexpected.

**How Hookdeck Can Help:** Hookdeck's request log shows the exact body each stream sends, which makes a legacy stream easy to spot.

## Best practices

### Verify the whole batch as bytes

The signature covers the entire array. In Express use `express.raw({ type: '*/*' })`, in Next.js `await request.arrayBuffer()` and in FastAPI `await request.body()`. Check for exactly 64 hex characters after the prefix before decoding.

### Treat it as telemetry

Route Convex log events to a logging or metrics system, and use them for dashboards and alerts. Keep business events, such as "order paid", in your own Convex functions where they are transactional.

### Separate deployments

Give dev and prod their own stream, secret and destination. A shared endpoint makes it easy to page someone over a dev error.

### Watch for truncation

`console` events carry `is_truncated`. Long log lines are cut, so don't rely on structured JSON inside a `console.log` message surviving intact.

### Answer quickly

Convex doesn't document a timeout, so return `200` as soon as the batch is stored. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## Conclusion

Convex's webhook log stream is a pipe for deployment telemetry: batched, signed, unfiltered and best effort. Verify the batch over its raw bytes, split it by `topic`, accept that some events will be missing or repeated, and keep anything business-critical out of the log path.

[Hookdeck Event Gateway](https://hookdeck.com) sits between Convex and your collector, verifying and storing each batch so problems on your side don't widen the gaps.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Convex webhooks reliably in minutes.