fix(ordinal): mark the 20 docs-sourced samples as docs-sourced (source block, no invented headers)

[garethx]

This PR is separate from #58 and adds no new samples. It corrects how the 20 existing providers/ordinal/ files are marked.

The defect

providers/ordinal/README.md says every file in latest/ is "docs-sourced and generated by a script" (scripts/ordinal/docs.ts). The files themselves didn't say so. All 20 had:

• no source block, which is the marking this repo's README gives doc-sourced samples ("marked with a source key that a captured sample never has"), and
• accept: */* and user-agent: Ordinal-Webhooks, taken from REPRESENTATIVE_HEADERS.

So each file looked like a capture. hookdeck/webhook-registry's paths.sample_provenance() found the two transport headers and no source block, and classified all 20 as likely-capture. Any consumer that trusts that classification treats doc examples as observed deliveries. The registry's ordinal row already records this as a misclassified-upstream gap.

Ordinal documents no User-Agent. The webhooks introduction page documents no vendor-set delivery header at all: no event-type header, no delivery id, no signature. The only headers a delivery is documented to carry are the static ones a subscriber configures in the webhook's headers field. So user-agent: Ordinal-Webhooks was invented, and so was accept.

The fix, in the generator

The output files weren't hand-edited. scripts/ordinal/AGENTS.md says to change them by re-running the generator, and that's what this PR does. docs.ts now:

1. Writes content-type: application/json only, backed by the introduction page's "The request body is JSON". No other header is written.
2. Adds source: {type: "vendor-documentation", url: <event page>, retrieved: <run date>} to every file.
3. Records provenance.latest: {sourced_via: "docs", sourced_on: <oldest retrieved>} in index.json. The oldest date is used so that a partial re-run can never overstate freshness. It was absent before, so the version published as unknown.
4. Discovers event pages whether or not llms.txt lists them with .md. It now lists them without .md, so the old regex found 0 pages and the generator exited with "no webhook event pages discovered". It couldn't be run until this was fixed. The script now fetches <page>.md for the markdown and cites the page URL itself in source.url.

providers/ordinal/README.md, scripts/ordinal/README.md and scripts/ordinal/AGENTS.md now say "content-type only, plus a source block" instead of "representative headers".

Results

check	result
yarn generate:ordinal	20/20 pages discovered and extracted, and all 20 expected events are present
bodies and topics vs main	all 20 unchanged, compared as parsed JSON. The diff covers headers, the new source block and index.json provenance, and nothing else.
idempotence	a second run on the same day produces no diff
source.url	all 20 return HTTP 200
paths.sample_provenance() (registry)	20/20 doc-example (was 20/20 likely-capture)
yarn compile	passes; 140 providers; ordinal publishes provenance.latest = {docs, 2026-09-28}
yarn test	14/14

After this merges, the registry side has follow-up to do: the ordinal row's samples.upstream_provenance gap, and its delivery_headers note quoting these headers, will both be stale.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
webhook-samples	Ready	Preview	Sep 28, 2026 4:14pm UTC