DEV Community

linkbruno.com
linkbruno.com

Posted on Edited on

Case study (hypothetical): after the domain change, every paying customer landed on a 404

Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com

This is a hypothetical case study. The company and numbers are invented, but every piece of it is a mistake I've seen at least once, and the combination is depressingly natural.

The setup

A small SaaS product rebrands. The app moves from app.oldname.io to app.newname.com. The team does the migration properly, by most standards:

  • Every old URL 301-redirects to the same path on the new domain.
  • The marketing site, docs and blog are crawled before and after, and the link checker reports zero broken internal links.
  • Email templates, the README and the help centre are updated.
  • The old domain stays registered, with redirects, for at least two years.

Launch day goes well. Traffic moves over, search rankings hold, and the team celebrates.

What broke

Checkout used a hosted payment page. When a customer clicks "Upgrade", the app creates a checkout session with the provider and sends the customer there. After paying, the provider redirects them back to a success URL. If they cancel, to a cancel URL. Customers manage cards in a hosted billing portal, which has a return URL. And the provider tells the app about payments through a webhook endpoint.

None of those URLs lived in the codebase in the same way:

  • The success and cancel URLs were built in code from an environment variable, APP_BASE_URL. It had been updated. But one of three services that create checkout sessions, the old "team plan" flow, had its own hard-coded fallback: https://app.oldname.io/billing/success?session_id={CHECKOUT_SESSION_ID}.
  • The billing portal return URL was set once in the provider's dashboard, two years earlier.
  • The webhook endpoint was also configured in the dashboard, pointing at https://app.oldname.io/webhooks/payments.

The old domain redirected, so you'd expect all of these to keep working. They didn't, for three different reasons.

The success URL lost its query string. The redirect rule on the old domain was written as "redirect every path to the same path on the new domain". It matched the path and dropped the query string. Customers arrived at /billing/success with no session_id, and the page, unable to look up the session, returned a 404. They had paid. The screen said "Page not found".

The webhook endpoint didn't follow redirects. Most payment providers don't follow redirects on webhook delivery; a 301 is treated as a failed delivery. Webhooks started failing quietly. The app never recorded the upgrades, so the paying customers stayed on the free plan.

The billing portal return link pointed at a page that had been renamed during the rebrand, from /settings/billing to /account/billing. The old path wasn't in the redirect map because the redirect map only covered path-for-path domain moves.

How it was found

Not by monitoring. A customer emailed: "I paid, got an error, and I'm still on Free. I tried again and got charged twice." Over the next two days support found 31 similar cases: 9 double payments, and 22 customers who'd given up after seeing the 404.

The link checker passed because it only checked pages, not the URLs your payment provider sends people to. linkbruno.com rechecks your links and redirects on a schedule, so a redirect that drops a query string or lands on a renamed page shows up in a report before a paying customer finds it.

The fix

  1. Redirects keep the query string. In Nginx that means return 301 https://app.newname.com$request_uri; rather than rebuilding the URL from $uri. They re-tested with real-looking URLs, query strings included.
  2. Webhook endpoint updated in the provider dashboard, and failed events replayed from the provider's event log. The app's handler was idempotent, so replays were safe, and the 22 missing upgrades appeared.
  3. Every external URL inventoried. They went through every dashboard where a URL is configured: payment provider (success, cancel, portal return, webhooks), OAuth apps (redirect URIs), email provider (link tracking domain), app stores, integrations marketplace listings, analytics. Fourteen URLs, most of them configured once by someone who no longer worked there.
  4. The hard-coded fallback removed and replaced with a startup check: the service refuses to boot if APP_BASE_URL is missing.
  5. Double payments refunded, with an apology email.

What I'd take from it

A domain migration has two link inventories, not one. The first is the links in your content and templates, which crawlers find. The second is the links configured in other people's systems that point at you: payment providers, OAuth apps, webhooks, marketplace listings. No crawler will ever find those. You have to list them.

Redirect rules must be tested with query strings. Payment, login and email-verification flows almost always carry state in the query string. A redirect that drops it breaks exactly the flows that matter most.

Webhooks and API callbacks don't follow redirects. Treat them as URLs that must be updated, not redirected.

Put the external URLs on your checks. Success, cancel and portal return pages should return 200 (with a test session ID, or at least a friendly page rather than a 404 without one). A short list of these URLs in a scheduled link check, in linkbruno.com or wherever you run yours, would have caught the renamed billing page on day one.

The pre-migration list I'd use now

Before the next domain change, I'd write this list first, and test every item against the new domain on staging: checkout success URL, checkout cancel URL, billing portal return URL, payment webhook endpoint, OAuth redirect URIs for each login provider, email link and tracking domains, password reset and verification links, invoice and receipt links, any URLs registered in app stores or integration marketplaces. Each one gets a real request with a realistic query string, and each one gets a named owner.

Related reading

Have you ever had a migration break a URL that lived in someone else's dashboard? Which dashboard was it?

Top comments (0)