Skip to content
WebDecoy Docs

Vercel Integration

The WebDecoy Vercel integration automatically blocks malicious IPs at the edge using Vercel’s Firewall API. When a detection occurs, WebDecoy can instantly add the IP to your Vercel project’s firewall deny list.

How It Works

Section titled “How It Works”
Detection Created
       │
       ▼
WebDecoy Rule Engine
       │
       ├─ Check integration rules
       │  ├─ Event type matches?
       │  ├─ Bot score threshold met?
       │  └─ Decoy filter matches?
       │
       ▼
Vercel Firewall API
       │
       └─ Add IP to deny list

When a detection triggers the integration, WebDecoy calls the Vercel Firewall API (/v1/security/firewall/config) to add the IP address to your project’s deny list.

Prerequisites

Section titled “Prerequisites”
  • Vercel account (Pro or Enterprise tier for Firewall access)
  • Vercel API token with appropriate permissions
  • A project deployed on Vercel

Getting a Vercel API Token

Section titled “Getting a Vercel API Token”
  1. Go to vercel.com/account/tokens
  2. Click Create Token
  3. Give it a name like “WebDecoy Integration”
  4. Set the scope:
    • For personal accounts: Full Account
    • For team accounts: Select the team
  5. Copy the token (you won’t see it again)

Setting Up the Integration

Section titled “Setting Up the Integration”
  1. Go to Integrations in the WebDecoy sidebar
  2. Click Vercel
  3. Click Add Vercel Integration
  4. Fill in the configuration:
FieldDescription
NameA friendly name for this integration
API TokenYour Vercel API token
Team IDFor team accounts, enter your team ID (optional for personal accounts)
Project IDScope to a specific project, or leave empty for all projects
ActionWhat to do when triggered (see below)
  1. Click Create Integration

Finding Your Team ID

Section titled “Finding Your Team ID”

For team accounts:

  1. Go to your Vercel dashboard
  2. Click on your team name
  3. Go to Settings → General
  4. Copy the Team ID (starts with team_)

Finding Your Project ID

Section titled “Finding Your Project ID”
  1. Go to your project in Vercel
  2. Click Settings → General
  3. Copy the Project ID (starts with prj_)

Action Types

Section titled “Action Types”
ActionDescription
Block IPAdd the IP to Vercel’s firewall deny list (403 response)
ChallengeLog only (challenge not supported by Vercel Firewall)
Log OnlyRecord the event without blocking

Trigger Configuration

Section titled “Trigger Configuration”

Event Types

Section titled “Event Types”

Choose when the integration should trigger:

OptionDescription
All DetectionsTrigger on any detection
High Risk OnlyOnly trigger when bot score >= 80

Minimum Bot Score

Section titled “Minimum Bot Score”

Set a threshold score (0-100). The integration only triggers for detections with a bot score at or above this value.

Recommended thresholds:

Use CaseThreshold
Aggressive blocking50+
Standard protection70+
Conservative (fewer false positives)85+

Decoy Filter

Section titled “Decoy Filter”

Optionally restrict the integration to specific decoys. Leave empty to trigger for all decoys in your organization.

Managing Integrations

Section titled “Managing Integrations”

View Status

Section titled “View Status”

Each integration shows:

  • Trigger Count - How many times it has fired
  • Failure Count - How many API calls failed
  • Last Triggered - When it last fired
  • Last Error - Most recent error message (if any)

Test Integration

Section titled “Test Integration”

Click Test to verify the integration is working. This sends a test request to the Vercel API.

Enable/Disable

Section titled “Enable/Disable”

Toggle integrations on or off without deleting them. Disabled integrations don’t process any detections.

Delete

Section titled “Delete”

Remove an integration entirely. This doesn’t remove any IPs already blocked in Vercel.

Best Practices

Section titled “Best Practices”

Do’s

Section titled “Do’s”
  • Start with “High Risk Only” to avoid false positives
  • Use a conservative bot score threshold initially (75+)
  • Scope to specific projects if you don’t need organization-wide blocking
  • Monitor the failure count for API issues
  • Test the integration after setup

Don’ts

Section titled “Don’ts”
  • Don’t use a personal access token for team projects
  • Don’t set the threshold too low (causes false positives)
  • Don’t ignore failure counts (may indicate permission issues)

Troubleshooting

Section titled “Troubleshooting”

”Unauthorized” Errors

Section titled “”Unauthorized” Errors”
  1. Verify your API token is correct
  2. Check the token hasn’t expired
  3. For team accounts, ensure the Team ID is set
  4. Verify the token has permission to modify firewall rules

”Project Not Found” Errors

Section titled “”Project Not Found” Errors”
  1. Verify the Project ID is correct
  2. Ensure the API token has access to the project
  3. For team projects, ensure the Team ID is also set

IPs Not Being Blocked

Section titled “IPs Not Being Blocked”
  1. Check the integration is active (not disabled)
  2. Verify the event type filters match your detections
  3. Check the bot score threshold isn’t too high
  4. Look for errors in the integration status

High Failure Count

Section titled “High Failure Count”
  1. Check the Last Error message
  2. Verify API token hasn’t been revoked
  3. Ensure you’re on a Vercel plan that includes Firewall access
  4. Check Vercel’s status page for outages

Vercel Firewall Limits

Section titled “Vercel Firewall Limits”

Be aware of Vercel’s limits:

LimitValue
IP rules per projectVaries by plan
API rate limits100 requests/minute

WebDecoy respects these limits and will report errors if limits are exceeded.

Viewing Blocked IPs in Vercel

Section titled “Viewing Blocked IPs in Vercel”

To see IPs blocked by WebDecoy:

  1. Go to your Vercel project
  2. Click Settings → Security → Firewall
  3. View the IP deny list
  4. WebDecoy blocks include a note: “Blocked by WebDecoy - Detection [ID]“

Removing Blocked IPs

Section titled “Removing Blocked IPs”

WebDecoy doesn’t automatically remove blocked IPs. To unblock:

  1. Go to your Vercel Firewall settings
  2. Find the IP in the deny list
  3. Remove it manually

Next Steps

Section titled “Next Steps”