A legacy domain retirement plan has to account for something a browser test never shows you: real, already-installed software out in the world that’s still quietly calling home to the old domain, long after the visible website has moved. Redirecting everything and considering the domain done breaks license checks, update servers, and payment webhooks that were never part of anyone’s manual testing.
Why “Redirect Everything and Walk Away” Breaks Real, Installed Software
A person clicking an old link is forgiving – they land on the new site and move on without noticing anything happened. Software calling an API endpoint is not forgiving in the same way. It expects a specific response, in a specific format, at a specific URL, and a redirect that a human wouldn’t even register can be enough to silently break that expectation for every installation still depending on it.
License and Update Check-Ins Still Calling the Old Domain
Every existing install of a licensed plugin or theme periodically calls back to its update server to check license validity and look for new versions – entirely in the background, with no user ever seeing it happen. If that update server’s URL sits on a domain you’ve now blanket-redirected, every one of those background requests is affected, whether or not anyone notices right away. Automatic update behavior depends entirely on these check-ins succeeding correctly.
The practical risk isn’t just a failed check that quietly retries later. Depending on how the license-check code handles an unexpected response, a redirected check-in can be misread as “license invalid” rather than “couldn’t reach the server,” deactivating a paying customer’s working install over what was really just a domain change on your end, not anything they did.
Payment Gateway Webhooks Don’t Reliably Survive a Redirect
This is the sharpest edge of the whole problem. A standard 301 redirect gets converted from a POST request into a GET request by many HTTP clients, including the ones payment gateways use to deliver webhooks. A webhook’s entire payload – the completed payment, the renewed subscription – travels in the POST body. Converting that request to a GET on its way to the new domain doesn’t just relocate it, it silently drops the data. The new endpoint receives an empty GET request, processes nothing, and returns a response that looks successful.
Carve out known webhook and license-check paths from the blanket redirect entirely, the same way the earlier Nginx setup carved out /wp-admin/, login, and cron:
# Let webhook and license endpoints keep resolving on the old domain -
# a redirected POST silently loses its body, breaking these entirely.
location ^~ /wp-json/edd/ {
try_files $uri $uri/ /index.php?$args;
}
location = /paypal-ipn/ {
try_files $uri =404;
}
location = /stripe-webhook/ {
try_files $uri =404;
}
WordPress’s Own Canonical Redirects Can Cause the Same Problem
Carving these paths out of your own redirect config isn’t always the whole fix. WordPress’s own canonical redirect logic can issue its own 301 – for a missing trailing slash, or a URL that doesn’t exactly match its expected canonical form – before the request ever reaches your webhook handler at all. The result is identical: a payment gateway’s POST request gets redirected by WordPress core itself, converted to a GET, and its payload is gone. Test the exact webhook URL registered with each gateway directly, not just the general path pattern, since this failure mode doesn’t care whether your Nginx config is correct.
A Realistic Retirement Timeline, Measured in Months
Existing installs check in on their own schedule, not yours, and some of them check in rarely. A retirement timeline measured in weeks assumes every install phones home frequently enough to notice a problem quickly. A realistic timeline is measured in months, giving slower-checking installs a real chance to encounter the new domain and adjust before the old one disappears entirely.
Ship One More Update Before Considering Any Old Domain Disposable
The most reliable fix isn’t a redirect at all – it’s shipping one final plugin or theme update that repoints the update-check and license-validation URLs directly to the new domain in the code itself. An install that’s updated even once after this change never depends on the old domain surviving. Only installs that never update again remain a real risk, and no redirect strategy was ever going to save those regardless.
This is worth treating as a required step in the migration itself, not an optional cleanup task for afterward. Prioritize shipping it before the old domain’s retirement clock starts, since every day it isn’t out is another day more installs are relying entirely on a redirect to hold, rather than on code that no longer needs one.
A Webhook That Stops Receiving Events Silently
For example, imagine a Stripe webhook endpoint on an old domain that starts blanket-redirecting to a new one. Stripe’s dashboard shows the webhook as active, with no error reported, because the redirected request does technically complete with a response. What it doesn’t show is that every event since the redirect went live arrived as an empty GET request and was silently ignored. Nobody notices until a customer’s subscription renewal never activates their license, days or weeks after the actual charge succeeded.
The Pitfall: “The Redirect Works in a Browser” Isn’t Proof Every System Does
Opening an old URL in a browser and watching it land correctly on the new site feels like confirmation everything is working. It only confirms that GET requests from a browser redirect correctly. It says nothing about POST requests from a payment gateway, an update-check API call, or any other automated system depending on that same domain. Test every dependent system on its own terms, not by proxy through a browser test that was never exercising the same code path in the first place.
Every payment gateway provides a way to send a real test event to a specific webhook URL on demand. Use it, against the exact URL as registered, after the redirect goes live – not a manual curl request that doesn’t replicate how the gateway’s own systems actually issue the request.
Your Legacy Domain Retirement Checklist
Before considering any old domain disposable, confirm:
- Every license and update check-in URL is either carved out of the redirect or already repointed by a shipped update
- Every payment gateway’s exact registered webhook URL has been tested directly, not assumed safe
- WordPress’s own canonical redirect behavior has been checked against those same webhook URLs
- A retirement timeline measured in months, not weeks, has been set and communicated
- At least one more update has shipped, repointing active installs before the old domain goes away
With legacy systems accounted for, the next step is active monitoring – watching the consolidated site closely through the highest-risk window, the first 90 days after launch.