Agent skill

Convex Webhooks Skill

Receive and verify Convex webhook log stream events. Use when setting up a Convex webhook log stream endpoint, debugging x-webhook-signature verification, or handling log events such as verification, console, function_execution, audit_log and scheduler_stats.

Install this skill

npx skills add hookdeck/webhook-skills --skill convex-webhooks


Convex (the reactive backend platform) has one outbound webhook: the webhook log stream (Pro plan). It sends HTTP POST requests to your URL whose body is a batch of deployment log events, signed with HMAC-SHA256.

When to Use This Skill

  • How do I receive Convex log stream webhooks?
  • How do I verify the x-webhook-signature header from Convex?
  • Why is my Convex webhook signature verification failing?
  • How do I handle function_execution, console or audit_log events from Convex?
  • Why does every Convex request contain an array of events?

Verification (core)

Convex sends x-webhook-signature: sha256=<lowercase hex>, the HMAC-SHA256 of the raw request body keyed with the secret as UTF-8 (not hex- or base64-decoded). Only the body is signed; no timestamp or id. Strip a leading sha256= (the bare digest is accepted too), check the hex shape, then compare in constant time.

Node (check the hex shape first: Buffer.from(x, 'hex') silently drops invalid characters):

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const received = signatureHeader.replace(/^sha256=/, '');
  if (!/^[0-9a-f]{64}$/i.test(received)) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(received.toLowerCase()), Buffer.from(expected));
}

Python (compare bytes, never str):

import hashlib, hmac, re

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    received = signature_header.removeprefix("sha256=").lower()
    if not re.fullmatch(r"[0-9a-f]{64}", received):
        return False
    computed = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received.encode("ascii"), computed.encode("ascii"))

Respond 401 for a missing, malformed or mismatched signature. In Express use express.raw({ type: '*/*' }) (Next.js: await request.arrayBuffer(); FastAPI: await request.body()) so the exact bytes are verified, and parse JSON only afterwards.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

There is no event header. The body is a JSON array of events (or one JSON object per line for JSONL streams); loop over it and dispatch on each event's topic. Every event also has timestamp (Unix ms) and convex (deployment metadata).

TopicDescription
verificationSent to confirm the log stream is working
consoleA console.log-style message from a function (log_level, message, function)
function_executionA function ran (status success/failure, execution_time_ms, usage)
audit_logA deployment change (audit_log_action, audit_log_metadata)
scheduler_statsScheduler lag and running job count (lag_seconds, num_running_jobs)
current_storage_usageSnapshot of storage use in bytes
concurrency_statsPer-minute function concurrency statistics
storage_api_bandwidthA file download from the storage HTTP API (egress_bytes)
ai_gateway_usageUsage for an AI Gateway inference (inference_id, cost)

See references/overview.md for payload details.

Important Headers

HeaderDescription
x-webhook-signaturesha256=<lowercase hex> HMAC-SHA256 of the raw body

Delivery is best effort and batched: events can be dropped under high throughput or duplicated by network retries, so process idempotently.

Setup with Hookdeck

In the Convex dashboard open Deployment Settings > Integrations, add a Webhook log stream with your Hookdeck source URL, and copy the HMAC secret it shows into the Hookdeck source's signing secret (Convex source type). See references/setup.md.

Environment Variables

CONVEX_WEBHOOK_SECRET=your_hmac_secret   # HMAC secret shown in the dashboard for the webhook log stream

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 convex --path /webhooks/convex

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →