Files
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

4.3 KiB
Raw Permalink Blame History

v1.6.0 Design: Webmention API Contract

Reconstructed on 2026-11-03 from the implementation; the original v1.6.0 document was lost. Later changes: v2.6.8–v2.7.2 (see CHANGELOG). This describes the code as of v2.10.1 (starpunk/routes/webmention.py, starpunk/webmention_processor.py, starpunk/__init__.py).

Related: ADR-063, background-worker.md, rate-limiting.md, W3C Webmention (https://www.w3.org/TR/webmention/).

Endpoint discovery (what we advertise)

  • Every text/html response gets Link: </webmention>; rel="webmention" when WEBMENTION_ENABLED (default true). It is added alongside other Link headers (v2.7.0; it used to replace them, e.g. the WebSub links).
  • The endpoint URL is relative to the site root.

POST /webmention (receiving)

Blueprint webmention, no authentication.

Request

  • application/x-www-form-urlencoded (spec) with source and target.
  • application/json with the same keys is accepted as an extension.

Processing order

  1. Rate limit (before_request, POST only): see rate-limiting.md. 429 if exceeded.
  2. source and target present.
  3. Both are http(s) URLs with a host, at most 2,048 characters.
  4. source != target.
  5. Target host and effective port equal SITE_URL's (host compared case-insensitively, default ports filled in; v2.7.0).
  6. The fragment is removed from target (spec 3.2.1), so #a and #b are one mention.
  7. Target must be a published note: path /note/<slug> resolving to a published note. Anything else (home page, tag pages, drafts, unknown slugs) is refused (v2.7.0; before, such mentions were stored but never shown).
  8. UPSERT into webmentions on (source_url, target_url): a new row is pending/pending; an existing row is set back to validation_status = 'pending' (an update or removal, spec 3.2.4), keeping its moderation status.

All fetching happens later in the worker (spec 3.2: asynchronous verification).

Responses (JSON)

Status Body When
202 {"status": "accepted", "message": "Webmention queued for verification"} Stored
400 {"error": "invalid_request", "error_description": "Missing required parameter: source"} (or target) Missing parameter
400 invalid_request / "Source must be a valid URL", "Target must be a valid URL" Bad URL
400 invalid_request / "Source and target must be different" Same URL
400 invalid_target / "Target URL is not on this site" Other host
400 invalid_target / "Target URL does not accept webmentions" Not a published note
429 rate_limit_exceeded with Retry-After Rate limited
500 server_error / "Failed to queue webmention" Database error

GET /webmention

Returns {"name": "Webmention endpoint", "spec": "https://www.w3.org/TR/webmention/"}. Not rate limited.

Deleted targets

A soft-deleted note's page answers 410 Gone ("This post has been deleted", v2.7.0), so senders can tell the post is gone. New webmentions to it are refused (step 7).

Content sanitisation (stored snippets)

webmention_processor.sanitize_content() uses nh3:

  • Allowed tags: p, br, strong, em, b, i, a, code, pre, blockquote.
  • Allowed attributes: a[href]; nh3 adds rel="nofollow noopener" to links (the original contract listed a[href, rel]; rel is set by nh3 rather than passed through).
  • Snippets are cut to ~500 characters and sanitised again so a cut never leaves a tag open (v2.7.0).
  • Author URL and photo are stored only if http(s) (v2.6.9); everything is rendered through Jinja autoescaping except the sanitised snippet.

Extracted fields

process_webmention() returns: mention_type (reply, like, repost, bookmark, mention), author_name, author_url, author_photo, content_snippet, source_post_url, source_uid, source_published (RFC 3339 UTC). See background-worker.md for how each is derived and database-schema.md for storage.

Sending (our requests to others)

  • Endpoint discovery and POST as in background-worker.md.
  • Body: source=<note permalink>&target=<url>, form-encoded.
  • User-Agent: StarPunk/<version> Webmention (+<SITE_URL>).
  • Any 2xx is success; redirects from the endpoint are not followed and count as failure (v2.7.0).