Signature verification

Every webhook delivery carries an HMAC signature you must verify before trusting the payload. The SDK does the work in one call — you pass the raw body, the signature header, and your webhook secret; it returns a typed event or throws.

How verification works

The full pattern

Express
Hono
Next.js App Router
Raw fetch / HTTP

import { VibeFollow, WebhookSignatureError } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

app.post('/webhooks/vibefollow', express.raw({ type: '*/*' }), (req, res) => {
  try {
    const event = vf.webhooks.constructEvent(
      req.body, // raw Buffer or string &mdash; NOT JSON.parse(body)
      req.headers['x-vibefollow-signature'],
      process.env.VIBEFOLLOW_WEBHOOK_SECRET!,
    );

    switch (event.type) {
      case 'email.opened':
        console.log('opened', event.data.draftId);
        break;
      case 'email.replied':
        console.log('reply tone:', event.data.tone);
        break;
      // …
    }

    res.sendStatus(204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(401);
    throw err;
  }
});

import { Hono } from 'hono';
import { VibeFollow, WebhookSignatureError } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });
const app = new Hono();

app.post('/webhooks/vibefollow', async (c) => {
  const rawBody = await c.req.text();
  const sig = c.req.header('x-vibefollow-signature');

  try {
    const event = vf.webhooks.constructEvent(
      rawBody,
      sig,
      process.env.VIBEFOLLOW_WEBHOOK_SECRET!,
    );
    // handle event.type
    return c.body(null, 204);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return c.body(null, 401);
    throw err;
  }
});

// app/api/webhooks/vibefollow/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { VibeFollow, WebhookSignatureError } from '@vibefollow/sdk';

export const runtime = 'nodejs'; // not 'edge' &mdash; needs node:crypto

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const sig = req.headers.get('x-vibefollow-signature');

  try {
    const event = vf.webhooks.constructEvent(
      rawBody,
      sig,
      process.env.VIBEFOLLOW_WEBHOOK_SECRET!,
    );
    // handle event.type
    return new NextResponse(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookSignatureError) {
      return new NextResponse(null, { status: 401 });
    }
    throw err;
  }
}

// Anywhere you have raw bytes + the signature header
import { VibeFollow, WebhookSignatureError } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

function handle(rawBody: Buffer | string, sigHeader: string) {
  try {
    const event = vf.webhooks.constructEvent(
      rawBody,
      sigHeader,
      process.env.VIBEFOLLOW_WEBHOOK_SECRET!,
    );
    return event;
  } catch (err) {
    if (err instanceof WebhookSignatureError) {
      throw new Error('401 unauthorized');
    }
    throw err;
  }
}

The header format

Verification is constant-time. The SDK uses crypto.timingSafeEqual so an attacker cannot derive the secret by timing your responses.

Why the raw body

The signature is computed over the exact bytes Vibefollow sent. If you parse the body first and re-serialise — key order, whitespace, escaped slashes — the recomputed HMAC differs from the header. The SDK accepts both Buffer and string for the body argument; it will not accept a parsed object.

Framework-specific notes:

Express

Mount express.raw({ type: '*/*' }) on the webhook route only — not globally, or every other route loses JSON parsing.

Hono / Cloudflare Workers

Call await request.text() and pass the string.

Next.js App Router

Read request.text() inside the route handler. Pin the route to runtime = 'nodejs'.

Fastify

Use the addContentTypeParser API to capture the raw buffer.

Replay protection

The header includes a Unix-seconds timestamp t. The SDK rejects any delivery whose timestamp is more than ±5 minutes from local time, which neutralises replay attacks against stale captured payloads. Override the tolerance if your environment has known clock drift:

const event = vf.webhooks.constructEvent(req.body, sigHeader, secret, {
  toleranceSeconds: 600, // accept up to &plusmn;10 minutes
});

Don’t widen it past necessity. Five minutes is the Stripe-standard window for the same reason — it balances clock drift against replay risk.

Errors you should handle

WebhookSignatureError — missing header

The X-Vibefollow-Signature header wasn’t on the request. Return 401.

WebhookSignatureError — malformed header

The header didn’t parse as t=…,v1=…. Return 401.

WebhookSignatureError — timestamp outside tolerance

The t is more than ±5 minutes from now. Return 401.

WebhookSignatureError — signature mismatch

The HMAC didn’t match. Either the secret is wrong, the body was modified in transit, or it’s a forgery. Return 401.

SyntaxError

The (verified) body was not valid JSON. This shouldn’t happen — return 500 and investigate.

In all WebhookSignatureError cases, return 401. Do not retry on your side — Vibefollow’s retry will pick it up if the failure was transient.

Edge-runtime caveats

Webhook verification uses node:crypto for HMAC. On Cloudflare Workers, enable the nodejs_compat flag in wrangler.toml:

compatibility_flags = ["nodejs_compat"]

Pure-edge runtimes without Node compatibility cannot use the SDK’s verifier in v1. A Web Crypto fallback is planned for a future major release.

Testing locally

Send a synthetic delivery to your handler with curl and a hand-computed signature:

BODY='{"type":"email.opened","id":"evt_demo","created":1747526400,"data":{}}'
TS=$(date +%s)
SIG=$(printf "%s" "$TS.$BODY" | openssl dgst -sha256 -hmac "$VIBEFOLLOW_WEBHOOK_SECRET" -binary | xxd -p -c 256)

curl -i http://localhost:3000/webhooks/vibefollow \
  -H "Content-Type: application/json" \
  -H "X-Vibefollow-Signature: t=$TS,v1=$SIG" \
  --data-raw "$BODY"

​How verification works

​The full pattern

​The header format

​Why the raw body

​Replay protection

​Errors you should handle

​Edge-runtime caveats

​Testing locally

How verification works

The full pattern

The header format

Why the raw body

Replay protection

Errors you should handle

Edge-runtime caveats

Testing locally