This is an exampleThe team, the product and the timings below are made up to show how a failure plays out. No real company, customer or measurement is described.
The incident, in order
- 1
09:10, a launch page goes into the CMS
A six-person product team runs a marketing site on a headless CMS and a static build. An editor prepares a partner announcement that links to a partner domain registered the week before.
- 2
09:14, the editor presses publish
The publish webhook calls a function. The function runs a linkback checker call against the partner domain and is written to block the release on any non-success answer.
- 3
09:14, the build never starts
Two things fail at once. The domain is brand new, so our index may not know it yet. Separately, the prepaid balance on the team's key was empty, so the paid follow-up call returned HTTP 402.
- 4
09:40, the team finds it
The editor reports a vague error. An engineer reads the function log, sees the 402 and the empty result, and spends twenty minutes working out which of the two caused the block.
- 5
10:05, the launch goes out by hand
Someone bypasses the hook with a manual deploy. The launch is 55 minutes late, and the bypass leaves no record of which checks were skipped.
Why it happened
The gate treated every non-success as a verdict. That was the root cause. A balance problem and an unknown domain are facts about the tooling and the index, and neither says anything about the page.
Our graph is rebuilt about once a month. A domain registered after the last refresh can look empty, and a new partner is the normal case for a launch page. Nobody had checked. The team had tested the hook only with old, well-known domains such as nytimes.com.
The second miss was silence. The function logged the error but sent no alert, and the editor saw a generic failure message with no hint that credit had run out.
Cost was never the issue. At 2 credits a call, the whole month of checks for this invented site came to about $0.60, the same figure as the 3,000-publish row in the cost table. The gate was cheap and still cost them an hour in 2026.
The 402 deserves its own line. A prepaid balance is a state you can watch, so a simple alarm at 10,000 credits, which is $1, would have fired days earlier.
Action items the team wrote
Owners are roles, not people. All items are part of the example.| Change | Owner | Why |
|---|
| Treat 402 as a skip plus an alert to the platform channel | Platform | Credit is a billing state, not a page state |
|---|
| Treat an empty result for a new domain as unknown, not bad | Platform | The index lags by about a month |
|---|
| Show the editor the reason in plain words | Editorial tooling | 20 minutes lost reading logs |
|---|
| Record skipped checks on the entry | Platform | Manual deploys left no trail |
|---|
| Test the hook with a domain registered this week | QA | Old domains hide the gap |
|---|
What to copy
Fail open on link data, fail loud on the alert
A link check should never be the only thing standing between an editor and a launch. Let the page through, tag the entry, and make the failure impossible to miss for the person who owns the key.
- Tell 401, 402 and an empty result apart in code
- Keep a balance alarm well above zero (see the cost table)
- Rehearse the failure on staging before launch day
A note on the hypothetical
Real teams will differ. Yours may fail closed for good reasons, such as a regulated site where every outbound link is reviewed by a person. Fine. Just make that a choice.
The webhook runbook lists the same decisions as a checklist, and the myth list covers the beliefs that led this invented team into the trap.