Skip to content
WebDecoy Docs

Vercel Integration

The WebDecoy Vercel integration adds IP rules to a Vercel project’s firewall through Vercel’s Firewall API. You can add a rule by hand today with Block an address on the integration’s page, under Changes on this provider. Automatic rules from detections are built but withheld until scores are calibrated; see What runs automatically today.

How It Works

Section titled “How It Works”
Detection Created
       │
       ▼
WebDecoy Rule Engine
       │
       ├─ Check integration rules
       │  ├─ Event type matches?
       │  ├─ Score threshold met?
       │  └─ Decoy filter matches?
       │
       ├─ Automatic blocking enabled for this scorer version?
       │  (currently withheld until calibration)
       │
       ▼
Vercel Firewall API
       │
       └─ Add IP to deny list

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

Prerequisites

Section titled “Prerequisites”
  • A Vercel plan whose Firewall allows IP rules
  • 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:
Field Description
Name A friendly name for this integration
API Token Your Vercel API token
Team ID (optional) For team accounts, enter your team ID
Project ID The project whose firewall WebDecoy writes to. Vercel has no account-wide firewall, so Block IP and Challenge need one; Log Only does not
Action What 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”
Action Description
Block IP Add the IP to Vercel’s firewall deny list (403 response)
Challenge Set the IP rule to Vercel’s challenge action, so matching requests are tested rather than refused
Log Only Record the event without blocking

Trigger Configuration

Section titled “Trigger Configuration”

Event Types

Section titled “Event Types”

Choose when the integration should trigger:

Option Description
All Detections Trigger on any detection
High Risk Detections (Score >= 80) Only trigger when the detection’s bot score is 80 or higher

Minimum Score (optional)

Section titled “Minimum Score (optional)”

Set a threshold score (0-100). The integration only triggers for detections whose threat score (unified_score, or the bot score when there is none) is at or above this value.

Recommended thresholds:

Use Case Threshold
Aggressive blocking 50+
Standard protection 70+
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.

Delete the integration and any rules it applied stay on Vercel permanently. The API token goes with the integration, so WebDecoy can no longer remove them, and their lifetimes stop being honoured. Reverse the rules you want gone before deleting, from the list of changes on the provider, or remove them from the Vercel dashboard yourself afterwards.

Disabling is the reversible option: a disabled integration stops acting on detections, and the rules it already applied are still tracked and still expire.

Best Practices

Section titled “Best Practices”

Do’s

Section titled “Do’s”
  • Start with High Risk Detections to avoid false positives
  • Use a conservative bot score threshold initially (75+)
  • 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 score threshold isn’t too high
  4. Remember that automatic blocking is currently withheld until scorer calibration
  5. 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:

Limit Value
IP rules per project Varies by plan

When Vercel refuses a change (for example over a limit), WebDecoy records the failure and its error on the integration.

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 rules carry a note of the form webdecoy:action:<id>, which identifies the change in WebDecoy’s list of changes on the provider

Removing Blocked IPs

Section titled “Removing Blocked IPs”

Every rule WebDecoy applies has a lifetime, and WebDecoy removes it when that expires. A rule nobody remembers making and nobody can explain a year later is the one this avoids. You can also reverse one yourself at any time, from Integrations → Vercel, under the list of changes on the provider.

The exception is deleting the integration: that takes the API token with it, so the rules it applied stay on Vercel and stop expiring. See Delete.

To remove one from Vercel’s side instead:

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

WebDecoy notices a rule you removed yourself the next time it checks, and records it as gone rather than continuing to claim the site is protected.

Next Steps

Section titled “Next Steps”