Gareth Wilson Gareth Wilson

Guide to Convex Webhooks: Features and Best Practices

Published


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

FeatureDetails
AvailabilityPro plan
ConfigurationDeployment Settings > Integrations > Webhook
SubscriptionNone. Every topic is sent
Signaturehex HMAC-SHA256
Signature headerx-webhook-signature, as sha256=<hex>
Signed contentThe raw request body, covering the whole batch
SecretGenerated by Convex and shown in the dashboard, one per stream
BodyJSON
Event routingBody field [].topic
DeliveryBest effort, batched. Events can be dropped under load or duplicated
Retries, timeout, IPsNot documented

Events and payloads

TopicTriggered WhenKey fields
verificationThe stream is created, to confirm it worksmessage
consoleA function calls the console APIfunction, log_level (DEBUG/INFO/LOG/WARN/ERROR), message, is_truncated
function_executionAny function runsfunction, execution_time_ms, status (success/failure), error_message, usage
audit_logA deployment change (also in the dashboard History tab)audit_log_action, audit_log_metadata (stringified JSON)
concurrency_statsOnce a minute, when stats changedquery, mutation, action, node_action, http_action (num_running, num_queued)
scheduler_statsPeriodically from the schedulerlag_seconds, num_running_jobs
current_storage_usagePeriodicallytotal_document_size_bytes, total_index_size_bytes, total_file_storage_bytes, ...
storage_api_bandwidthA client downloads a file from the storage HTTP APIstorage_id, egress_bytes
ai_gateway_usageAn AI Gateway inference endsinference_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 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:

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, 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.

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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.