---
title: "Let Good Bots In"
description: "Bot Protection challenges TidePay's payment webhook along with the bad bots. Write a bypass rule for the webhook, put it first, and prove the bypass is safe because the route checks the signature. Then see why verified bots like AI assistants never needed one."
canonical_url: "https://vercel.com/academy/vercel-firewall/let-good-bots-in"
md_url: "https://vercel.com/academy/vercel-firewall/let-good-bots-in.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-11-17T18:26:11.970Z"
content_type: "lesson"
course: "vercel-firewall"
course_title: "Protect Your App on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Let Good Bots In

# Let good bots in

Every lunch order at Claw & Order waits on one message. TidePay, the payment provider, calls the truck to say the customer paid, and only then does anyone start buttering rolls. That call comes from TidePay's servers.

In 4.1 we turned on a layer that challenges anything that isn't a browser. Nobody checked on TidePay.

## Outcome

TidePay's webhook gets through Bot Protection with a bypass rule, an unsigned request to the same route still gets turned away, and the scalper stays challenged.

## Oh no, TidePay

Place a lunch order from your browser and copy the order id from the confirmation. Then play TidePay, telling the truck the order is paid:

```bash
npm run webhook -- <order-id> --target "$URL"
```

Challenged. A webhook is a server talking to a server, so it's the least browser-like traffic there is. Find it in the log the way you'd find any surprise:

```bash
vercel firewall traffic list --since 10m --path /api/webhooks/payment --dimension rule --dimension user-agent
```

`TidePay-Webhooks/1.0`, challenged by Bot Protection. Big payment providers are in Vercel's [verified bots directory](https://vercel.com/docs/bot-management#verified-bots-directory), and Bot Protection skips those automatically. TidePay is made up, so it's not in the directory. Plenty of real providers aren't either.

## A bypass rule

A [bypass rule](https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets#bypassing-rulesets) is a custom rule whose action lets matching requests skip the rules after it, including the managed rulesets. Put one on the webhook path:

```bash
vercel firewall rules add "TidePay webhook" \
  --condition '{"type":"path","op":"eq","value":"/api/webhooks/payment"}' \
  --condition '{"type":"method","op":"eq","value":"POST"}' \
  --action bypass \
  --description "Server-to-server payment events; the route checks the signature" \
  --yes
vercel firewall rules move "TidePay webhook" --first --yes
vercel firewall diff
vercel firewall publish --confirm-name claw-and-order
```

Bot Protection is a managed ruleset, and managed rulesets always run after every custom rule, so the bypass would skip it from any position. We still put it first. A bypass also skips the custom rules below it, so first in line means a rule added later, even a deny on a bad day, can't stall TidePay's payments by accident.

\*\*Note: That's your third custom rule\*\*

On Hobby, `Pinchy's scraper`, `Preorder rush`, and `TidePay webhook` use up the [custom rule allowance](https://vercel.com/docs/vercel-firewall/vercel-waf#limits). The rest of the course doesn't add any.

## What the bypass doesn't check

Look at what this rule doesn't ask: who's calling. Anyone can POST to `/api/webhooks/payment` now, and the Firewall will wave them through. That's safe only because `app/api/webhooks/payment/route.ts` verifies TidePay's signature on every request and returns `401` without it, and only if the secret is secret.

The route falls back to `tidepay_test_secret` so the drill works out of the box, and that value sits in a public repo. Generate a real one, give it to the deployment, and redeploy:

```bash
export TIDEPAY_WEBHOOK_SECRET=$(openssl rand -hex 32)
printf %s "$TIDEPAY_WEBHOOK_SECRET" | vercel env add TIDEPAY_WEBHOOK_SECRET production
vercel deploy --prod
```

The `export` makes `attack/payment-webhook.mjs` sign with the same value the deployment checks. It only lasts for this terminal, so keep the value somewhere safe. A new terminal needs the same `export` before the script will get past the signature check. Bypass the Firewall only on routes whose code checks the caller itself.

## Marguerite's assistant never needed one

Marguerite's AI assistant has been placing Harborview's lunch order all along, with no bypass rule. AI assistants from the big providers are verified bots, so Bot Protection skips them, and in 4.1 we set the AI Bots ruleset to allow the assistants category.

Bots Vercel can verify are the managed rulesets' job, using the choices you made in 4.1. Anything else that calls the truck on purpose, like TidePay or an uptime monitor, needs a bypass rule from you and a route that checks who's calling.

## Hands-on exercise 4.2

Find the good bot that got caught and let it back in safely.

**Requirements:**

1. Place a lunch order, run the webhook script, and confirm TidePay gets challenged.
2. Find TidePay in the traffic report and confirm which rule caught it.
3. Add a `TidePay webhook` bypass rule for `POST /api/webhooks/payment`, move it first, and publish.
4. Set `TIDEPAY_WEBHOOK_SECRET` on the deployment, redeploy, and export the same value locally.
5. Pay for a fresh order and confirm an unsigned request is rejected.
6. Snapshot your rules and commit.

**Implementation hints:**

- The webhook script reads the order id from its first argument. Use an id from an order you placed today, since orders expire after a day.
- `printf` pipes the value into `vercel env add`, so you type it zero times. Any long random string works.
- `vercel firewall rules list` shows the order rules run in.

## Try It

Place a new lunch order from `/order` in your browser and copy its id. Then pay for it:

```bash
npm run webhook -- <order-id> --target "$URL"
```

```text
TidePay → https://claw-and-order.vercel.app/api/webhooks/payment
  200 {"received":true,"id":"<order-id>","status":"paid"}
```

TidePay gets through, and the order is paid. Now check the bypass didn't open the route to anyone with a forged event:

```bash
curl -s -X POST "$URL/api/webhooks/payment" \
  -H "content-type: application/json" \
  -d '{"type":"payment.succeeded","orderId":"<order-id>"}'
```

```text
{"error":"Bad signature"}
```

The Firewall let it through and the route stopped it, which is the arrangement we wanted. Last, make sure the bypass is scoped. The scalper should still be challenged everywhere else:

```bash
npm run scalper -- scrape --target "$URL" --count 3 --disguise
```

## Commit

```bash
vercel firewall rules list --json > firewall/rules.json
git add firewall/rules.json
git commit -m "chore(firewall): bypass Bot Protection for the TidePay webhook" \
  -m "Safe because the route verifies the HMAC signature. TIDEPAY_WEBHOOK_SECRET set in production."
```

## Done-When

- [ ] You found TidePay in the traffic report, challenged by Bot Protection
- [ ] `TidePay webhook` is the first custom rule, with a bypass action on `POST /api/webhooks/payment`
- [ ] `TIDEPAY_WEBHOOK_SECRET` is set on the deployment, and the webhook script marks an order paid
- [ ] An unsigned request to the webhook gets `Bad signature`
- [ ] The disguised scraper is still challenged
- [ ] `firewall/rules.json` is committed

## Troubleshooting

**The webhook still gets challenged after you publish.** Run `vercel firewall diff`. If it lists changes, the rule never went live, so run `vercel firewall publish --confirm-name claw-and-order`. Otherwise check the conditions with `vercel firewall rules inspect "TidePay webhook"`: the path must be exactly `/api/webhooks/payment` and the method `POST`.

**The webhook returns `401 Bad signature` after you set the secret.** Your terminal is signing with a different value. Export the same `TIDEPAY_WEBHOOK_SECRET` you gave the deployment, then run the script again.

**The webhook returns `404 Unknown order`.** The id has a typo, or the order is more than a day old and expired. Place a new lunch order and use its id.

## Solution

The bypass, and the secret that makes it safe:

```bash
# Find the good bot that got caught
npm run webhook -- <order-id> --target "$URL"
vercel firewall traffic list --since 10m --path /api/webhooks/payment --dimension rule --dimension user-agent

# Let it back in, first in line
vercel firewall rules add "TidePay webhook" \
  --condition '{"type":"path","op":"eq","value":"/api/webhooks/payment"}' \
  --condition '{"type":"method","op":"eq","value":"POST"}' \
  --action bypass \
  --description "Server-to-server payment events; the route checks the signature" \
  --yes
vercel firewall rules move "TidePay webhook" --first --yes
vercel firewall publish --confirm-name claw-and-order

# Keep the bypass safe
export TIDEPAY_WEBHOOK_SECRET=$(openssl rand -hex 32)
printf %s "$TIDEPAY_WEBHOOK_SECRET" | vercel env add TIDEPAY_WEBHOOK_SECRET production
vercel deploy --prod

vercel firewall rules list --json > firewall/rules.json
git add firewall/rules.json
git commit -m "chore(firewall): bypass Bot Protection for the TidePay webhook"
```

The lunch order finally says "paid," and every script that isn't TidePay still hits the challenge.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)
