Vercel Logo

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:

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:

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, 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 is a custom rule whose action lets matching requests skip the rules after it, including the managed rulesets. Put one on the webhook path:

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.

That's your third custom rule

On Hobby, Pinchy's scraper, Preorder rush, and TidePay webhook use up the custom rule allowance. 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:

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:

npm run webhook -- <order-id> --target "$URL"
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:

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

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

Commit

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:

# 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.

Was this helpful?

supported.