- 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>
4.3 KiB
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/htmlresponse getsLink: </webmention>; rel="webmention"whenWEBMENTION_ENABLED(default true). It is added alongside otherLinkheaders (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) withsourceandtarget.application/jsonwith the same keys is accepted as an extension.
Processing order
- Rate limit (
before_request, POST only): see rate-limiting.md. 429 if exceeded. sourceandtargetpresent.- Both are http(s) URLs with a host, at most 2,048 characters.
source != target.- Target host and effective port equal
SITE_URL's (host compared case-insensitively, default ports filled in; v2.7.0). - The fragment is removed from
target(spec 3.2.1), so#aand#bare one mention. - 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). - UPSERT into
webmentionson(source_url, target_url): a new row ispending/pending; an existing row is set back tovalidation_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 addsrel="nofollow noopener"to links (the original contract listeda[href, rel];relis 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).