Node.js SDK
Server-side integration for verifying bot scanner results and accessing the WebDecoy API from your Node.js backend.
npm install @webdecoy/node
// or
yarn add @webdecoy/node
// or
pnpm add @webdecoy/nodeWhat 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.
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
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
});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');
});Webhook Validation
All webhooks from WebDecoy are signed with HMAC-SHA256. The SDK provides utilities to validate these signatures.
Framework Examples
The SDK works with any Node.js framework.
Express
Fastify
Next.js
NestJS
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.
Learn More About Server-Side Integration
Guides and tutorials for integrating WebDecoy into your backend.
SDK Launch: TLS Fingerprinting
Learn how JA3/JA4 fingerprinting detects bots by analyzing TLS handshakes.
SIEM Integration Guide
Forward bot detections to Splunk, Elastic, and CrowdStrike for SOC visibility.
WebDecoy & WAAP Integration
How WebDecoy fits into your Web Application and API Protection strategy.
See also: Bot Scanner for client-side detection, Threat Scoring for automated responses, and Integrations for WAF connections.
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