Vercel protection bypass in a Sume webhook URL

If your Vercel preview deployment is protected, a Sume webhook can still reach it by adding the bypass secret to the URL as the x-vercel-protection-bypass query parameter. Vercel documents that form for tools that cannot set headers. Sume keeps the query string when it delivers, so this works, but the secret then appears in the webhook URL on the run receipt, so give it a dedicated secret and keep verifying the Sume signature.

The Vercel facts are from Protection Bypass for Automation, read 2026-10-10. The Sume facts are from Run webhooks and Webhooks.

What does Vercel offer?

The page says Protection Bypass for Automation is available on all plans. The recommended way is the x-vercel-protection-bypass header; the same name is accepted as a query parameter for tools that cannot set headers. A project can hold more than one secret, and VERCEL_AUTOMATION_BYPASS_SECRET is set automatically as a system environment variable. The bypass does not skip active DDoS mitigations. Regenerating a secret requires a redeploy before it takes effect.

What does Sume accept in the URL?

The rules come from the webhook URL check in the repository. The URL must be public HTTPS and at most 2048 characters. Credentials in the URL, an explicit port, and private or localhost hosts are refused. The URL is checked again at delivery time, and redirects are not followed, so a redirect from the protected preview to a login page fails the attempt. The query string is kept: delivery uses the path and the search together.

Sume signs the body with its own secret, which is a separate value, so rotating one never touches the other. Keep both in your project settings and never print either in a log line; request logs on the receiving side often record the full URL including the query string.

That makes a URL like https://my-preview.example.vercel.app/api/sume?x-vercel-protection-bypass=SECRET valid, as long as you use the real hostname that does not redirect.

Who can see the secret?

The receipt's webhook_delivery object shows the url, the delivery status, the number of attempts and the signing_secret_fingerprint. The URL is shown as you sent it, so anyone with access to the run receipt can read the bypass secret. For a team that shares keys, that is a wide audience.

Mitigate in three ways: create a bypass secret used for Sume only, regenerate it when people leave, and never reuse it for the public. Vercel's own page says multiple secrets are allowed, which is what makes this cheap.

Is the bypass enough to trust the call?

No. The bypass only gets the request past Vercel's protection. Anyone who learns the URL could post to it. Verify the HMAC-SHA256 signature in x-sume-webhook-signature over <timestamp>.<raw_body> with the signing secret before reading the event. The Verifying webhooks page documents the async verifyWebhook helper, which returns false for a bad delivery and has a 300 second replay window by default.

Then dedupe on request_id and return 2xx quickly.

One practical note on testing. Send a test delivery with POST /v1/webhooks/test-deliveries; it sends a webhook.test event so you can see the bypass, the signature check and your handler work together before a real paid run depends on them. If the test fails with a redirect, look at the deployment alias first, since a redirect counts as a failure.