Vercel Log Drains Webhooks Skill

Vercel Log Drains forward deployment logs to any HTTPS endpoint you configure. These are HTTP log-drain deliveries (not "Vercel webhooks" and not Standard Webhooks): Vercel POSTs batches of log entries and signs the raw body with HMAC-SHA1.

When to Use This Skill

• How do I receive Vercel Log Drains?
• How do I verify the x-vercel-signature header?
• How do I complete the x-vercel-verify endpoint handshake?
• Why is my Vercel log drain signature verification failing?
• How do I parse batched log entries (JSON array or NDJSON)?
• How do I handle logs from lambda, edge, build, or firewall sources?

Verification (core)

Vercel signs the raw request body with HMAC-SHA1 keyed on your drain's signature secret and sends the hex digest in the x-vercel-signature header (the raw digest — no sha1= prefix). Use the raw body (do not re-serialize), and compare timing-safe.

Node:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha1', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signatureHeader, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false; // wrong length / not hex
  }
}

Python:

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha1).hexdigest()
    return hmac.compare_digest(signature_header, expected)

Endpoint handshake (x-vercel-verify)

When a drain is created or tested, Vercel sends an unsigned probe request. Your endpoint must respond 200 OK with an x-vercel-verify response header echoing the verification token shown in the dashboard. Because the probe is unsigned, treat a request with no x-vercel-signature as the handshake: return 200 with the verify header and do not process logs. Signed deliveries then carry x-vercel-signature; reject those with an invalid signature (403).

For complete handlers with route wiring, log parsing, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Log Sources (the "event" dimension)

Log drains do not have named event types. Each log entry carries a source field — dispatch on it the way you would on an event type.

Each entry also has a level (info, warning, error, fatal). A statusCode of -1 means the lambda crashed with no response.

For the full log schema, see Vercel Log Drains Reference.

Delivery Formats

A single request contains a batch of log entries in one of two encodings (set per drain):

• JSON — a JSON array of log objects: [{…},{…}]
• NDJSON — one JSON object per line (newline-delimited)

Handlers should support both (optionally gzip-compressed). Message fields may be truncated when they exceed 256 KB.

Important Headers

Environment Variables

VERCEL_LOG_DRAIN_SECRET=your_drain_signature_secret   # Team Settings > Drains > Edit
VERCEL_VERIFY=your_verification_token                  # shown when creating the drain

Local Development

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

Reference Materials

• references/overview.md - What log drains are, sources, log schema
• references/setup.md - Dashboard and REST API configuration
• references/verification.md - Signature verification and the verify handshake