Skip to main content
HumanKey
Wersja polska →

Documentation

Integration guides for WordPress, JavaScript, REST API, and webhooks.

On this page

Quick Start

Most setups take under 2 minutes. Choose the method that fits your platform:

Quick Setup

→WordPress Plugin~2 min→1-Line JS Snippet~60 secRECOMMENDED

Developer / Server-Side

→REST API~20 min→AI Crawler RulesAfter setup

Need real-time notifications? Webhooks are available after tracking is live (Business & Enterprise).

WordPress Plugin

The official HumanKey plugin installs directly from the WordPress plugin directory.

  1. 1Go to your WordPress Admin → Plugins → Add New
  2. 2Search for "HumanKey" and click Install Now
  3. 3Activate the plugin
  4. 4Navigate to Settings → HumanKey
  5. 5Paste your Site Public Key (found in your Dashboard → Sites)
  6. 6Save — the tracking snippet is now live on all pages

What the plugin adds

  • • Injects the HumanKey tracking snippet in your site's <head>
  • • Adds an AI Traffic dashboard panel in WP Admin
  • • Shows live bot/human traffic stats without leaving WordPress
  • • Displays your HumanKey Verified badge status

1-Line JS Install

Works on any platform that allows custom HTML: Shopify, Webflow, Squarespace, static sites, and custom apps.

<!-- Add to your <head> tag -->

<script

src="https://humankey-production.up.railway.app/api/detect.js"

data-site-key="YOUR_PUBLIC_KEY"

async

></script>

Replace YOUR_PUBLIC_KEY with your site's public key from the Dashboard → Sites page.

Platform-specific guides

  • • Shopify: Settings → Themes → Edit Code → theme.liquid → paste in <head>
  • • Webflow: Project Settings → Custom Code → Head Code
  • • Squarespace: Settings → Advanced → Code Injection → Header
  • • Custom HTML: Paste before the closing </head> tag

REST API (Server-Side)

Use the REST API from your server to detect bots and AI crawlers before serving content. Ideal for Next.js middleware, Laravel, Django, or any server-side framework.

Bot Detection — POST /api/detect

// Request

POST https://humankey-production.up.railway.app/api/detect
Content-Type: application/json

{
  "siteKey": "pk_...",
  "url": "https://yoursite.com/article",
  "referrer": "https://google.com"
}

// Response

{
  "isHuman": false,
  "confidence": 0.99,
  "action": "block",
  "bot": {
    "name": "GPTBot",
    "company": "OpenAI",
    "purpose": "training"
  }
}

The action field tells you what to do: block → return 429, monitor → log and continue, allow → explicitly permitted crawler.

Next.js Middleware example

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export async function middleware(req: NextRequest) {
  const res = await fetch('https://humankey-production.up.railway.app/api/detect', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      siteKey: process.env.HK_PUBLIC_KEY,
      url: req.url,
      referrer: req.headers.get('referer') ?? undefined,
    }),
  });

  const { action } = await res.json();

  if (action === 'block') {
    return new NextResponse('Too Many Requests', { status: 429 });
  }

  return NextResponse.next();
}

AI Crawler Rules (Block / Monitor / Allow)

Configure per-crawler rules in your Dashboard → Sites → AI Crawler Rules.

Block

Crawler receives "action": "block". Your server-side code should return 429 Too Many Requests.

GPTBotCCBotanthropic-ai

Monitor

Default for all detected crawlers. Logged in your dashboard, traffic passes through.

PerplexityBotApplebot

Allow

Explicitly permitted crawlers. Useful for crawlers you want to index your content.

Googlebotbingbot

HumanKey also generates a custom robots.txt snippet based on your rules. Install it via the WordPress plugin with one click, or copy and paste it manually.

Webhooks

Get real-time notifications when bots are detected. Available on Business and Enterprise plans.

Supported events

  • bot.detected
  • quota.warning
  • quota.exceeded
  • plan.upgraded

Example payload

POST https://your-endpoint.com/webhook
X-HumanKey-Signature: sha256=...

{
  "event": "bot.detected",
  "data": {
    "domain": "yoursite.com",
    "botName": "GPTBot",
    "confidence": 0.99,
    "url": "/article/ai-trends-2026"
  }
}

Signatures use HMAC-SHA256. Verify with your webhook signing secret from Dashboard → Webhooks.

Embeddable Badge

Display an embeddable "HumanKey Verified" badge on your site to show visitors you monitor AI traffic.

<img
  src="https://humankey-production.up.railway.app/api/badge?siteKey=YOUR_PUBLIC_KEY"
  alt="HumanKey AI Verified"
  width="180"
  height="20"
/>

The badge is an SVG image served with a 1-hour cache. No JavaScript required.

Can't find what you need?

Our support team responds within 2 business days.

Contact Support