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_, 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
- Open the Deployment Settings of the deployment in the Convex dashboard and select the Integrations tab.
- Choose the Webhook card.
- Enter your endpoint URL. It is the only setting.
- 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:
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.
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.
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 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,timestampandfunction.request_idwhere 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
topicin 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.
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 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 for free and handle Convex webhooks reliably in minutes.