Loading...
Loading...
Verify and handle webhooks delivered through the Hookdeck Event Gateway. Use when receiving webhooks via Hookdeck and need to verify the x-hookdeck-signature header. Covers signature verification for Express, Next.js, and FastAPI.
npx skill4agent add hookdeck/webhook-skills hookdeck-event-gateway-webhooksx-hookdeck-signaturex-hookdeck-signatureconst crypto = require('crypto');
function verifyHookdeckSignature(rawBody, signature, secret) {
if (!signature || !secret) return false;
const hash = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('base64');
try {
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
} catch {
return false;
}
}import hmac
import hashlib
import base64
def verify_hookdeck_signature(raw_body: bytes, signature: str, secret: str) -> bool:
if not signature or not secret:
return False
expected = base64.b64encode(
hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
).decode()
return hmac.compare_digest(signature, expected)# Required for signature verification
# Get from Hookdeck Dashboard → Destinations → your destination → Webhook Secret
HOOKDECK_WEBHOOK_SECRET=your_webhook_secret_from_hookdeck_dashboardconst express = require('express');
const app = express();
// IMPORTANT: Use express.raw() for signature verification
app.post('/webhooks',
express.raw({ type: 'application/json' }),
(req, res) => {
const signature = req.headers['x-hookdeck-signature'];
if (!verifyHookdeckSignature(req.body, signature, process.env.HOOKDECK_WEBHOOK_SECRET)) {
console.error('Hookdeck signature verification failed');
return res.status(401).send('Invalid signature');
}
// Parse payload after verification
const payload = JSON.parse(req.body.toString());
// Handle the event (payload structure depends on original provider)
console.log('Event received:', payload.type || payload.topic || 'unknown');
// Return status code — Hookdeck retries on non-2xx
res.json({ received: true });
}
);import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';
function verifyHookdeckSignature(body: string, signature: string | null, secret: string): boolean {
if (!signature || !secret) return false;
const hash = crypto.createHmac('sha256', secret).update(body).digest('base64');
try {
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
} catch {
return false;
}
}
export async function POST(request: NextRequest) {
const body = await request.text();
const signature = request.headers.get('x-hookdeck-signature');
if (!verifyHookdeckSignature(body, signature, process.env.HOOKDECK_WEBHOOK_SECRET!)) {
return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
}
const payload = JSON.parse(body);
console.log('Event received:', payload.type || payload.topic || 'unknown');
return NextResponse.json({ received: true });
}import os
import json
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
@app.post("/webhooks")
async def webhook(request: Request):
raw_body = await request.body()
signature = request.headers.get("x-hookdeck-signature")
if not verify_hookdeck_signature(raw_body, signature, os.environ["HOOKDECK_WEBHOOK_SECRET"]):
raise HTTPException(status_code=401, detail="Invalid signature")
payload = json.loads(raw_body)
print(f"Event received: {payload.get('type', 'unknown')}")
return {"received": True}For complete working examples with tests, see:
- examples/express/ - Full Express implementation with tests
- examples/nextjs/ - Next.js App Router implementation with tests
- examples/fastapi/ - Python FastAPI implementation with tests
| Header | Description |
|---|---|
| HMAC SHA-256 signature (base64) — verify this |
| Unique event ID (use for idempotency) |
| Original request ID |
| Source that received the webhook |
| Destination receiving the webhook |
| Delivery attempt number |
| What triggered this attempt: |
| Seconds until next automatic retry (absent on last retry) |
| URL to view event in Hookdeck dashboard |
| Whether Hookdeck verified the original provider's signature |
| IP of the original webhook sender |
stripe-signaturex-hub-signature-256.digest('base64').digest('hex')express.raw({ type: 'application/json' })crypto.timingSafeEqualhmac.compare_digestx-hookdeck-*# Install Hookdeck CLI
brew install hookdeck/hookdeck/hookdeck
# Or: npm install -g hookdeck-cli
# Start tunnel to your local server (no account needed)
hookdeck listen 3000 --path /webhooks// Generated with: hookdeck-event-gateway-webhooks skill
// https://github.com/hookdeck/webhook-skills