Server Integration

Node.js SDK

Server-side integration for verifying bot scanner results and accessing the WebDecoy API from your Node.js backend.

Installation
npm install @webdecoy/node

// or
yarn add @webdecoy/node

// or
pnpm add @webdecoy/node

What the SDK Does

The Node.js SDK provides server-side utilities for working with WebDecoy detections.

Verify Detections

Server-side verification of bot scanner results to prevent client-side tampering.

Query Detections

Access your detection history and analytics data through the API.

Webhook Validation

Validate HMAC signatures on incoming webhook payloads.

Basic Usage

Quick Start

Initialize the SDK with your API key and start verifying bot scanner results from your backend.

API Key Authentication

Use your API key from the WebDecoy dashboard

Async/Await Support

Modern Promise-based API

TypeScript Types

Full type definitions included

Example Usage
import { WebDecoy } from '@webdecoy/node';

const webdecoy = new WebDecoy({
  apiKey: process.env.WEBDECOY_API_KEY
});

// Verify a bot scanner token
app.post('/api/submit', async (req, res) => {
  const token = req.headers['x-webdecoy-token'];

  const result = await webdecoy.verify(token);

  if (result.isBot && result.score > 70) {
    return res.status(403).json({
      error: 'Bot detected'
    });
  }

  // Process legitimate request
});
Webhook Validation
import { validateWebhook } from '@webdecoy/node';

app.post('/webhooks/webdecoy', (req, res) => {
  const signature = req.headers['x-webdecoy-signature'];
  const payload = req.body;

  const isValid = validateWebhook(
    payload,
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the detection event
  const { detection_type, threat_score, ip } = payload;

  console.log(`Detection: ${detection_type}, Score: ${threat_score}`);

  res.status(200).send('OK');
});
Security

Webhook Validation

All webhooks from WebDecoy are signed with HMAC-SHA256. The SDK provides utilities to validate these signatures.

HMAC-SHA256 signature verification
Timestamp validation to prevent replay attacks
Constant-time comparison

Framework-Specific Packages

Install the core SDK or use our framework-specific packages with built-in middleware.

Core SDK

npm install @webdecoy/node

Works with any framework

Express

npm install @webdecoy/express

Middleware included

Fastify

npm install @webdecoy/fastify

Plugin included

Next.js

npm install @webdecoy/nextjs

Middleware wrapper

Express.js

Express Middleware

The Express package provides middleware that automatically analyzes every request and attaches detection results.

Global or per-route middleware
Configurable block threshold
Path exclusions for static assets
Detection results on req.webdecoy
Express Middleware
import express from 'express';
import { webdecoyMiddleware } from '@webdecoy/express';

const app = express();

// Apply globally
app.use(webdecoyMiddleware({
  apiKey: process.env.WEBDECOY_API_KEY,
  sensitivity: 'medium',
  blockThreshold: 70,
  exclude: ['/health', '/static/*']
}));

// Or per-route
app.post('/api/login',
  webdecoyMiddleware({ blockThreshold: 50 }),
  (req, res) => {
    // Access detection results
    const { score, threatLevel } = req.webdecoy;

    if (req.webdecoy.shouldChallenge()) {
      return res.status(429).json({
        error: 'Please complete verification'
      });
    }

    // Process login...
  }
);
Fastify Plugin
import Fastify from 'fastify';
import webdecoyPlugin from '@webdecoy/fastify';

const fastify = Fastify();

// Register the plugin
await fastify.register(webdecoyPlugin, {
  apiKey: process.env.WEBDECOY_API_KEY,
  sensitivity: 'medium'
});

fastify.post('/api/checkout', async (req, reply) => {
  // Detection attached to request
  const detection = req.webdecoy;

  if (detection.score > 80) {
    return reply.code(403).send({
      error: 'Request blocked'
    });
  }

  if (detection.shouldChallenge()) {
    return reply.code(429).send({
      error: 'Verification required',
      challengeUrl: '/verify'
    });
  }

  // Process checkout...
});
Fastify

Fastify Plugin

Register WebDecoy as a Fastify plugin. Detection data is automatically attached to every request object.

Native Fastify plugin architecture
Async/await throughout
High-performance request handling
Full TypeScript support
Next.js

Next.js Middleware

Protect your Next.js app at the edge with middleware that runs before every request.

Edge Runtime compatible
App Router and Pages Router support
Route-level protection decorators
Server Actions protection
middleware.ts
import { withWebDecoy } from '@webdecoy/nextjs';
import { NextResponse } from 'next/server';

export default withWebDecoy({
  apiKey: process.env.WEBDECOY_API_KEY,

  // Handle detection results
  onDetection: async (detection, request) => {
    if (detection.score > 80) {
      return NextResponse.json(
        { error: 'Blocked' },
        { status: 403 }
      );
    }

    if (detection.shouldChallenge()) {
      return NextResponse.redirect(
        new URL('/verify', request.url)
      );
    }

    return NextResponse.next();
  }
});

export const config = {
  matcher: ['/api/:path*', '/checkout/:path*']
};

Detection Response

Every detection returns a comprehensive analysis with actionable methods.

Detection Object
{
  "score": 78,
  "threatLevel": "HIGH",
  "flags": [
    "headless_browser",
    "webdriver_detected",
    "canvas_anomaly"
  ],
  "signals": {
    "webdriver": true,
    "headless": true,
    "canvasAnomaly": true,
    "mouseEntropy": 0.12
  },
  "ip": "203.0.113.42",
  "userAgent": "Mozilla/5.0...",
  "timestamp": "2025-12-13T22:30:00Z"
}

Threat Levels

MINIMAL (0-29) — Likely human
LOW (30-49) — Some signals
MEDIUM (50-69) — Suspicious
HIGH (70-89) — Likely bot
CRITICAL (90-100) — Confirmed bot

Helper Methods

shouldBlock() Score ≥ block threshold
shouldChallenge() Score in challenge range
isLegitimate() Score below thresholds

Why Use Server-Side Bot Detection

Client-side detection is powerful, but server-side verification makes it tamper-proof.

Tamper-Proof Verification

Attackers cannot modify bot scores or bypass detection by manipulating client-side JavaScript. Server verification is the final authority.

TLS Fingerprinting

The SDK adds JA3/JA4 TLS fingerprint analysis that can only be done server-side, catching bots that spoof browser user agents.

Real-Time Webhooks

Receive instant notifications when bots are detected. Trigger automated responses in your backend without polling.

Available SDKs

WebDecoy provides official SDKs for multiple languages and platforms.

Node.js

Express, Next.js, NestJS, Fastify. Full TypeScript support.

npm install @webdecoy/node

Go

High-performance Go SDK for net/http handlers.

View Go documentation

PHP / WordPress

WordPress plugin and PHP SDK for custom integrations.

View PHP documentation

Frequently Asked Questions

Common questions about the WebDecoy Node.js SDK.

Why do I need server-side verification with the SDK?

Client-side bot detection can be tampered with by sophisticated attackers. The SDK allows you to verify detection tokens server-side, ensuring that bot scores have not been modified. This two-layer approach combines client-side signals with tamper-proof server verification.

Which Node.js frameworks are supported?

The SDK works with any Node.js framework including Express, Fastify, Next.js, NestJS, Koa, and Hapi. It provides simple middleware integration patterns and works with both JavaScript and TypeScript projects with full type definitions included.

How do I validate incoming webhooks from WebDecoy?

The SDK includes a validateWebhook function that verifies HMAC-SHA256 signatures on incoming webhook payloads. This ensures webhooks are genuinely from WebDecoy and have not been tampered with. The function also validates timestamps to prevent replay attacks.

What data does the verification response include?

Verification responses include the bot score (0-100), detection signals (webdriver, headless, canvas anomaly, etc.), a human/bot verdict, the visitor ID, and the timestamp. You can use this data to make access control decisions in your application.

Are there SDKs for other languages besides Node.js?

Yes. WebDecoy also provides SDKs for Go and PHP (with WordPress integration). All SDKs support the same core functionality: token verification, webhook validation, and API access. See our documentation for Go and PHP integration guides.

Ready to integrate server-side bot detection?

Install the Node.js SDK and start verifying bot scanner results in minutes.

View npm Package