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-signatureheader from Convex? - Why is my Convex webhook signature verification failing?
- How do I handle
function_execution,consoleoraudit_logevents 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).
| Topic | Description |
|---|---|
verification | Sent to confirm the log stream is working |
console | A console.log-style message from a function (log_level, message, function) |
function_execution | A function ran (status success/failure, execution_time_ms, usage) |
audit_log | A deployment change (audit_log_action, audit_log_metadata) |
scheduler_stats | Scheduler lag and running job count (lag_seconds, num_running_jobs) |
current_storage_usage | Snapshot of storage use in bytes |
concurrency_stats | Per-minute function concurrency statistics |
storage_api_bandwidth | A file download from the storage HTTP API (egress_bytes) |
ai_gateway_usage | Usage for an AI Gateway inference (inference_id, cost) |
See references/overview.md for payload details.
Important Headers
| Header | Description |
|---|---|
x-webhook-signature | sha256=<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
- references/overview.md - Log stream concepts, topics and payloads
- references/setup.md - Creating the webhook log stream and getting the HMAC secret
- references/verification.md - Signature verification details and gotchas