# Webpoke

> Restoring truth and sanity to webhooks: a signed, content-free poke plus a cursor-owned ranged pull turns webhook delivery failure into latency instead of corruption.

Webpoke is a sudo science lab investigation into event delivery. The site is a single-page doctrine — styled as an "executive order, event delivery division" — arguing that webhooks should never carry payloads. Instead, the notification is a signed, content-free poke ("the frontier is at or beyond X"), and the data contract is a cursor-owned ranged pull (`GET /changes?since=<cursor>`) over an append-only ledger. Truth lives in the pullable ledger; sanity is a durable cursor the consumer owns. Every failure mode — lost, duplicated, or reordered pokes — degrades to latency, never to corruption, because consumers also poll on a heartbeat floor. And because the poke is content-free, a forged, replayed, or dropped one cannot corrupt a consumer; it can only suggest re-reading a ledger the consumer verifies for itself — trust the data, not the transport.

The page covers:

- **The order**: the four-part contract — signed content-free poke, `GET /changes?since=<cursor>` range reads with opaque cursors and a stated replay window, a heartbeat poll floor, and a consumer-owned checkpoint (one durable row per consumer).
- **Findings**: what payload-bearing webhooks actually cost — delivery becomes the correctness mechanism, the "don't rely on webhooks" disclaimer is an unpriced liability transfer, the payload's value goes negative, and the universal receiver-plus-internal-bus workaround is the confession.
- **Precedent**: providers that already converged on poke + pull at scale — Dropbox, Google Drive, Plaid (`/transactions/sync`), Stripe (`GET /v1/events`), Salesforce Pub/Sub, Kafka/CDC consumer-owned offsets, and RFC 5005 archived Atom feeds.
- **Lineage**: the pattern is RSS/Atom read clearly — Greg Young's event-sourced read model. The feed is the log, polling is underrated (304-cacheable conditional GET), history is immutable and CDN-able (RFC 5005), and signing the events is the one addition that lets untrusted relays carry them.
- **The general shape**: the same invariant under every sync protocol — decentralized social firehoses (an ATProto repo is a signed commit log replayed from a seq cursor), ActivityPub as the cautionary push-on-write opposite, and the Kafka / CDC / Matrix / Nostr / IMAP / NNTP family. Notifications are hints, signed logs are truth, cursors belong to the consumer.
- **Dividends**: offset pull is multi-consumer by construction — permissionless consumers, consumer isolation, history through the same channel, and replay as an operation rather than a project.
- **Code on demand**: the consumer can ship a cheap, sandboxed WASM filter/map/reduce to the `GET /changes` query side, so the ranged pull is narrowed, projected, or folded before it crosses the wire — pull your slice, not the firehose. WASM keeps it cheap and safe (resource-capped, no network or disk); the provider can meter and bill the pushed-down compute as a SKU. Fielding's optional code-on-demand constraint, finally earning its keep.
- **The rubric**: three ordered questions for choosing push vs. poke + pull — is there an authoritative versioned store, is the notification reducible to a monotone fact, and is floor latency tolerable when the channel fails.
- **Deliverable**: ship the stateful half of the SDK — consumer runtime modules (poke receiver, cursor row, ranged-pull worker, fan-out + DLQ) as ~200 lines of IaC in three reference stacks (AWS, GCP, plain Postgres).
- **Status**: doctrine drafted (this page); reference stack demo filmed (https://youtu.be/kSyE4aoNthE — poke cut, heartbeat recovery, poke abuse, consumer isolation); the changes-endpoint spec is a sketch; consumer runtime modules are on the roadmap.

## Links

- Demo video (reference stack walkthrough): https://youtu.be/kSyE4aoNthE
- Canonical project page: https://sudoscience.dev/projects/webpoke
- Parent lab: sudo science, an industrial research lab — https://sudoscience.dev (machine-readable summary: https://sudoscience.dev/llms.txt)
- Terms: https://sudoscience.dev/terms
- Privacy: https://sudoscience.dev/privacy
- Contact: hello@sudoscience.dev