We have spent this series arguing, in principle, what AI-ready documentation looks like. This post is the practice. One page, rebuilt from scratch, with every artifact shown: the original, the AI's answer against the original, the restructured version, and the AI's answer against the restructured version.

It is the most important post in the series, and the hardest one to fake.

The thesis, restated#

The argument for AI-ready documentation is only as strong as the before-and-after. A single page, rewritten with retrieval in mind, should measurably change the quality of the AI answer built on top of it. If it doesn't, the framework is wrong.

This post shows one page where it does, and names what changed.

The page we're rebuilding#

We picked webhook signature verification. Three reasons.

First, every backend engineer has written this code. If the AI answer is wrong, a reader notices immediately. No hand-waving gets past it.

Second, it is high-stakes. A webhook endpoint with broken verification is a production security incident. "Close enough" is not close enough.

Third, it exhibits every failure mode we have cataloged in this series: a task buried under a generic section title, prose-wrapped code the chunker can't hold together, a version drift nobody owned, and a silent prerequisite. Fix this one page and you fix the pattern.

The example vendor is a fictional Northvane Pay with an SDK called northvane-webhooks. The structure mirrors real webhook pages we've audited at payment, messaging, and observability vendors.

Artifact 1 — The page, as it was#

The original lived at /docs/webhooks. It had grown for three years, one pull request at a time, and it showed.

# Webhooks

Northvane Pay uses webhooks to notify your application when events happen
in your account, like a successful charge or a refund. You can configure
webhook endpoints from the Developers section of the dashboard.

## Receiving events

When an event occurs, Northvane sends an HTTP POST to the URL you configured,
with a JSON body describing the event. Your endpoint should respond with
a 2xx status code within 10 seconds. If it doesn't, we retry with
exponential backoff for up to 24 hours.

## Security

Every webhook request includes an `Northvane-Signature` header. You should
verify this signature before trusting the payload. To verify, take the
raw request body, compute an HMAC-SHA256 using your webhook secret as
the key, and compare the result to the signature in the header. If they
match, the request came from Northvane.

In Node.js, you can use the `northvane-webhooks` SDK. Install it with
`npm install northvane-webhooks@1.4.2` and call `northvane.webhooks.verify(body, header, secret)`,
which returns true or false. Make sure to pass the raw body, not the parsed JSON,
or the signature check will fail. Here is an example using Express:
`app.post('/webhook', (req, res) => { const ok = northvane.webhooks.verify(req.body,
req.headers['northvane-signature'], process.env.NORTHVANE_SECRET); if (ok) { res.sendStatus(200); }
else { res.sendStatus(400); } })`. Remember to configure Express to give you
the raw body with `express.raw({ type: 'application/json' })`.

## Event types

See the Events reference for the full list of event types we send.

Count the problems.

There is no task title. The page is called "Webhooks," not "Verify a webhook signature." The retriever sees a generic topic, not an answer to a question.

There are no prerequisites. The reader, and the retriever, must infer that you need webhooks enabled in the dashboard and a signing secret already provisioned.

The code is stranded inside a paragraph. A retriever that chunks by paragraph or by a 400-token window pulls the prose and loses the code, or pulls the code and loses the express.raw setup that makes it work.

The SDK version is pinned to 1.4.2. The current version at time of writing is 3.x, and the v3 API surface changed: verify was replaced by constructEvent, which also enforces a timestamp tolerance. Nobody regenerated the sample when v2 shipped. Nobody regenerated it when v3 shipped.

And the biggest one: the page never mentions replay protection. No timestamp check, no tolerance window, no warning that a captured payload can be resent tomorrow and will still verify. This is the difference between signed and safe.

Artifact 2 — The AI's answer against the original#

We ran the following query against a standard RAG pipeline over this docs set: OpenAI text-embedding-3-large, 512-token chunks with 64-token overlap, top-5 retrieval, GPT-class generator with a "answer only from the provided context" system prompt. No rerankers, no query rewriting. This is the baseline most teams actually ship.

Query: "How do I verify a webhook signature in Node?"

Response:

To verify a webhook signature in Node.js with Northvane Pay, install the
northvane-webhooks SDK and use the verify() method. Northvane signs every webhook
with an HMAC-SHA256 of the raw request body, and the signature is sent
in the Northvane-Signature header.

  npm install northvane-webhooks

Then in your Express handler:

  const northvane = require('northvane-webhooks');

  app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const ok = northvane.webhooks.verify(
      req.body,
      req.headers['northvane-signature'],
      process.env.NORTHVANE_SECRET
    );
    if (ok) {
      // handle event
      res.sendStatus(200);
    } else {
      res.sendStatus(400);
    }
  });

Make sure to pass the raw body, not the parsed JSON, or the signature
check will fail.

It reads well. It will run. It is wrong in two ways that matter.

The API is two major versions out of date. verify does not exist on the v3 SDK; the code will throw TypeError: northvane.webhooks.verify is not a function the first time it runs against a current install. The model inherited the staleness from the page.

There is no replay protection. An attacker who captures one valid webhook can replay it indefinitely. The AI didn't invent this omission; the source page never mentioned the timestamp header, so the retriever had nothing to surface.

Scored against the retrieval-audit rubric from earlier in this series:

Accuracy: 1 of 2. Syntactically valid, semantically wrong SDK.
Completeness: 0 of 2. Missing replay protection and the dashboard prerequisite.
Currency: 1 of 2. Pattern is current-ish; version is two majors behind.
Total: 2 of 6. Failure.

An engineer who trusts this answer ships a replay-vulnerable endpoint against an SDK method that doesn't exist. They will notice the second problem in thirty seconds. They may never notice the first.

What specifically was wrong with the page#

Not "the page was bad." Four named failures, each mapped to a retrieval behavior.

No canonical task title. The H1 was "Webhooks," a topic, not "Verify a Webhook Signature (Node.js)," a task. Dense retrievers weight the title heavily. A task-shaped query ("how do I verify...") matches a task-shaped title far better than a topic-shaped one.
Silent prerequisite. The page assumed webhooks were enabled and a signing secret existed. Neither appeared as retrievable text. The retriever cannot surface what the page does not say.
Inline code in prose. The Express example was wrapped in a paragraph. A 512-token chunker splits on paragraph boundaries and punctuation; it tore the example across chunk boundaries, and top-k retrieval returned a partial snippet without the express.raw configuration that makes it work.
Unowned version pin. The sample was frozen at 1.4.2. When the SDK went to 3.x, the code sample became a liability. Nobody owned sample regeneration, so nobody did it.

Each failure is independently fixable. Fixing them together is the point.

Artifact 3 — The page, restructured#

Same topic, same approximate length, composed differently. The new page lives at /docs/webhooks/verify-signature-node and reads like this.

---
title: Verify a Webhook Signature (Node.js)
task: verify-webhook-signature
runtime: node
sdk: northvane-webhooks
sdk_min_version: 3.0.0
requires:
  - webhooks_enabled
  - signing_secret_provisioned
last_verified: 2026-03-14
---

# Verify a Webhook Signature (Node.js)

Verify that an incoming webhook came from Northvane and has not been replayed.
This page covers the Node.js SDK. For other runtimes, see
[Verify a Webhook Signature (Python)](/docs/webhooks/verify-signature-python)
or [Verify a Webhook Signature (Go)](/docs/webhooks/verify-signature-go).

## Prerequisites

- Webhooks enabled for your account. See [Enable Webhooks](/docs/webhooks/enable).
- A signing secret from the dashboard. See [Get Your Signing Secret](/docs/webhooks/signing-secret).
- `northvane-webhooks` version `3.0.0` or later.
- Node.js 18 or later.

## Verify and handle the event

Use `constructEvent`. It performs the HMAC-SHA256 check, enforces a
five-minute timestamp tolerance to block replays, and returns the parsed
event. Pass the raw request body, not the parsed JSON.

```js
// npm install northvane-webhooks@^3
const express = require("express");
const { Webhooks } = require("northvane-webhooks");

const app = express();
const webhooks = new Webhooks({ secret: process.env.NORTHVANE_SIGNING_SECRET });

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = webhooks.constructEvent({
      payload: req.body,
      signatureHeader: req.headers["northvane-signature"],
      toleranceSeconds: 300,
    });
  } catch (err) {
    // InvalidSignatureError or TimestampOutOfToleranceError
    return res.status(400).send(`Webhook rejected: ${err.message}`);
  }

  // Respond quickly; do heavy work on a queue.
  res.sendStatus(200);
  enqueue(event);
});
```

## What `constructEvent` checks

1. The `Northvane-Signature` header parses and contains a `t=` timestamp and
   a `v1=` signature.
2. `HMAC_SHA256(secret, t + "." + rawBody)` equals the `v1` value, compared
   in constant time to prevent timing attacks.
3. The timestamp is within `toleranceSeconds` of the current time. This
   is the replay check. Do not skip it.

## Common mistakes

- Parsing the body before verification. JSON re-serialization changes bytes
  and breaks the HMAC. Always use `express.raw`.
- Logging the signing secret. Treat it like a password.
- Skipping the timestamp check by setting `toleranceSeconds` to a large
  value. A five-minute window is the default for a reason.

## Related tasks

- [Retry and idempotency for webhook handlers](/docs/webhooks/retries)
- [Rotate your signing secret](/docs/webhooks/rotate-secret)
- [Test webhooks locally with the CLI](/docs/webhooks/local-testing)

Same length, different composition. The title is the task. The prerequisites are structured data, not buried prose. The code is a single fenced block that survives any reasonable chunker. The replay check is named, explained, and defended against the most common way people disable it. Related topics are linked, not inlined, so the retriever doesn't confuse this page with the page about rotation.

The frontmatter is not decoration. task, runtime, sdk, and sdk_min_version become metadata filters the retrieval layer can use to disambiguate ("Node" vs. "Python," "v3" vs. "v2"). last_verified is the handle by which automation flags stale pages. requires is machine-readable prerequisite data that downstream tools, including the AI, can surface as a checklist.

Artifact 4 — The AI's answer against the restructured page#

Same pipeline, same query, same model. Only the source page changed.

Query: "How do I verify a webhook signature in Node?"

Response:

To verify a webhook signature in Node.js with Northvane Pay:

Prerequisites:
  - Webhooks enabled for your account.
  - A signing secret from the dashboard.
  - northvane-webhooks v3.0.0 or later on Node.js 18+.

Use constructEvent from the northvane-webhooks SDK. It verifies the HMAC-SHA256
signature, enforces a 5-minute timestamp tolerance to block replays, and
returns the parsed event. You must pass the raw request body.

  const express = require('express');
  const { Webhooks } = require('northvane-webhooks');

  const app = express();
  const webhooks = new Webhooks({ secret: process.env.NORTHVANE_SIGNING_SECRET });

  app.post(
    '/webhook',
    express.raw({ type: 'application/json' }),
    (req, res) => {
      let event;
      try {
        event = webhooks.constructEvent({
          payload: req.body,
          signatureHeader: req.headers['northvane-signature'],
          toleranceSeconds: 300,
        });
      } catch (err) {
        return res.status(400).send(`Webhook rejected: ${err.message}`);
      }
      res.sendStatus(200);
      enqueue(event);
    }
  );

Notes:
  - Do not parse the body before verification; express.raw is required.
  - Do not widen toleranceSeconds to work around clock drift; fix the clock.

Scored:

Accuracy: 2 of 2. Correct SDK, correct method, correct shape.
Completeness: 2 of 2. Prerequisites named, replay check named, common mistake flagged.
Currency: 2 of 2. v3 API, current Node LTS.
Total: 6 of 6.

The model didn't get smarter between runs. The page did.

What this one page cost#

Time to restructure, end to end: roughly ninety minutes. Thirty minutes to audit the original against the rubric and name the four failures. Forty-five minutes to write the replacement, including verifying the v3 API against the SDK changelog. Fifteen minutes for review and linking.

Downstream effects we would expect, based on patterns we see repeatedly across webhook and auth docs:

A meaningful drop in signature-related support tickets over the following quarter. The exact number depends on ticket volume and tagging hygiene; teams we've worked with typically see somewhere in the range of a 20 to 50 percent reduction on the specific topic once the page stops generating wrong answers.
A retrieval-audit score lift across adjacent queries, because the new page's links and frontmatter pull neighboring pages (retry, rotation, local testing) into better retrieval neighborhoods.
A reduction in AI answer hallucinations on this topic to near zero, because the page now contains every fact the model needs and nothing it can round to the wrong thing.

Verify the specifics against your own instrumentation. The direction is reliable; the magnitude is yours to measure.

What this does not prove#

One page is not a doc set. The point of this post is not "rewrite every page this way tomorrow." The point is that the change is tractable, the improvement is measurable, and the structural pattern is repeatable. Earlier posts in this series named the pattern. This post shows it working.

To find your own candidate, run the retrieval audit from the previous post, sort by failed-query count, and pick the single page that breaks the most queries. Rewrite that one. Score it before and after. Then decide what to do next with evidence instead of argument.

Closing#

If you take one thing from this series, take this: the debate about whether your docs are AI-ready is a debate you can end with one page and one afternoon. Pick the worst offender, rewrite it against the rubric, score the AI answer before and after, and let the numbers talk.

If the numbers move, you have your answer, and your next ten pages.

If they don't, write to us. We want to see the page that breaks the pattern.