aka “Restoring Truth and Sanity to Webhooks”
# a poke with a hint, then a ranged pull
Webhooks should not deliver truth in flight. A signed, content-free poke plus a cursor-owned ranged pull turns every delivery failure into latency instead of corruption.
The doctrine is named for the 2025 executive order that promised to restore truth and sanity to history; this one settles for event delivery. Truth lives in a pullable ledger; sanity is a cursor you own.
Payload-bearing webhooks make delivery the correctness mechanism, which means providers owe signatures, ordering, retry queues, idempotency, dead-letter handling, and replay consoles — then disclaim it all with "don't rely on webhooks," transferring the reconciliation engineering to every consumer independently.
Move the contract from delivery to cursor. The provider keeps an append-only ledger and sends best-effort pokes; the consumer owns one durable checkpoint and reads ranges from it. Monotone facts can be lost, duplicated, or reordered harmlessly — so the channel gets to be cheap and the data gets to be correct.
the contract
"Something changed for this stream, frontier ≥ X." Nothing in it is load-bearing; every poke subsumes all earlier ones.
Ordered, bounded pages over an append-only ledger, with opaque cursors and a stated replay window.
Consumers poll anyway every N minutes. A consumer that missed every poke self-heals; nobody operates a replay console.
One durable row. At-least-once, duplication, reordering, and gap recovery all collapse into "read from my checkpoint."
vendor-shipped consumer
Every provider ships the stateless client — the easy 20% — and abandons consumers at the part that breaks in production. Webpoke inverts it: the vendor ships the stateful half, as deployable infrastructure, and the consumer writes one function.
Terraform / CDK / CloudFormation modules per cloud: poke receiver → cursor row → ranged-pull worker → fan-out → DLQ. ~200 lines of IaC, three flavors (AWS, GCP, plain Postgres-in-a-container).
The consumer's entire obligation is handle(events): everything around it — checkpointing, ordering, retries, fan-out by stream or type — arrives already provisioned and already correct.
Replay is "rewind the cursor." Shadow-running a new consumer version is "same stream, second checkpoint, diff the outputs." These ship as runbook commands, not aspirations.
The module the vendor hands partners is the same converger pattern it runs internally. Integration stops being a spec PDF and becomes "deploy this, write your function."
agent-operated onboarding
The last mile — wiring the vendor's consumer runtime into your stack — is itself delegable. Not by inventing a new trust ceremony, but by granting a vendor integration agent exactly the permissions that existing consent mechanisms already know how to scope, display, and revoke.
An AWS CloudFormation quick-create link (or Marketplace listing, or Terraform Cloud run) stands up the poke receiver, cursor table, and pull worker under a stack-scoped IAM role. The consent screen is the cloud's own — reviewed, logged, revocable.
The integration agent assumes only the role the stack created: this queue, this table, this log group. Cloud-side permissioning already solved least-privilege delegation; the agent just rides it.
Granted a GitHub App installation with the standard permission prompt, the agent wires the handler stub into your codebase following your conventions and opens a pull request — review remains yours.
The agent replays a sample range from cursor zero through your handler in shadow mode and attaches the output diff to the PR as evidence. The cursor makes the rehearsal free.
Delete the stack, uninstall the app, rotate the grant. Because the consumer owns the checkpoint, tearing the agent out never threatens the data.
dividends
A new consumer is a reader with credentials and a cursor at zero. Producer cost is O(1) in consumer count — immutable history is the most cacheable workload there is.
A slow consumer is just behind. No provider retry queues backing up, no "we deregistered your endpoint for failing too often."
Bootstrap by starting at zero — same channel, same code path, no backfill API, no seam.
Rewind, re-read, shadow-run, diff. There is no webhook-shaped version of blue-green consumption.
Filed by Rhett's ethos agent (by hand, for now): s2.dev — "the API for unlimited, durable, real-time streams." Durable, ordered, append-only streams readable from any retained point by sequence number or timestamp, with tailing, fencing tokens, and a self-hostable lite build. Relation: credible_actor, implementation_reference; impact: supports — the changes endpoint can be a thin shim over a stream store, and the lab has receipts: desh's stream-in/stream-out POC already replays through S2.
the rubric
Push — durable and acked for imperatives (a lost command is lost intent), fire-and-forget for samples nobody re-reads.
Then the lattice tricks don't apply; you need delivery semantics and should pay for them knowingly.
Still build poke + pull — then harden only the poke channel, the half whose failures can't corrupt anything.
artifacts
webpoke.sudoscience.dev
opaque cursors, bounded pages, replay window, signed poke — and an explicit retention floor, so falling behind the window is a declared gap condition, not a surprise
a TLA+ model of poke + hint + offset with passing TLC runs: safety invariants, plus the liveness property that is the whole doctrine — consumers reach the head even when every poke is dropped. "Failure is latency, not corruption," checked rather than asserted
Stripe, GitHub, Shopify, Svix, and Outpost scored against one rubric, each system's pain sorted into essential versus accidental complexity. The headline row: consumer-owned offset checkpoint in the protocol — no, for every vendor. The field still centers on delivery orchestration; that's the column this doctrine deletes
AWS, GCP, Postgres reference stacks
one-click provision + PR-based wiring + shadow verification
edges
absorbed prior work — named, never shipped, not available
An Optic-era observation that never shipped: APIs are only a subset of how organizations communicate. One place to document business processes and expose their endpoints and integration points — webhooks included. Webpoke is the integration-point half, finished.
Distilled from field notes on poke + ranged-pull systems, reactivity models, and the consumer runtime providers never shipped.