Webmention is a simple way to notify any URL when you mention it on your site. From the receiver's perspective, it's a way to request notifications when other sites mention it.
— W3C Specificatie
Er is bij webmentions sprake van een Zender (een pagina die een link plaatst) en een Ontvanger (waarnaar gelinkt wordt). Er kan nog een derde partij bij betrokken worden (Vouch), die het vertrouwen in de Zender kan uitspreken.
Verzenden
-
Zender schrijft een pagina met daarop een link naar Ontvanger.
-
Zender onderzoekt de link van Ontvanger op aanwezigheid van een
rel=webmentionlink (als HTTP-header, als<link>of als<a>, in die volgorde). -
Zender stuurt een POST-request (
application/x-www-form-urlencoded) naar Ontvanger, met in de body:source=<url van Zender>&target=<url van Ontvanger> -
Ontvanger geeft een 20x-header terug om het succes te vieren.
-
Voor wijzigingen worden nieuwe webmentions gestuurd naar alle Ontvangers in de orginele post (ook als die eruit verwijderd zijn), en naar eventuele nieuwe Ontvangers. Ook voor "bekende" URLs moet de discovery opnieuw worden uitgevoerd.
Ontvangen
-
Bij het ontvangen van een request op de webmention-URL, geeft Ontvanger een status terug:
- 201 + Location indien er een statuspagina te tonen is
- 202 indien het request asynchroon wordt afgehandeld (evt met body, die dan human readable is)
- 200 als het request synchroon wordt afgehandeld
-
Een eventueel URL-fragment wordt genegeerd.
-
Ontvanger stuurt een request naar de in de webmention genoemde
source, met een HTTP Accept-header om een voorkeur van content-types aan te geven. -
De URL van de opgegeven
targetmoet in de response voorkomen. -
Ontvanger kan op dat moment "iets met die content doen", bijvoorbeeld weergeven. Hierbij komen microformats goed van pas.
-
Als er iets fout gaat vanwege een fout van de Verzender, geeft Ontvanger een status 400 terug (met eventueel een toelichting).
-
Als er iets fout gaat aan de kant van Ontvanger, dan geeft deze een 500 terug.
-
Ontvanger moet oppassen dat een
source-URL niet gebruikt wordt om sneaky DOS-attacks uit te voeren (dus rate-limiting, limieten aan hoeveelheid data die wordt opgehaald, hoe lang op een respons wordt gewacht, etc.), of onbedoeld lokale URLs probeert op te vragen (localhost).
Wijzigingen
- Als Ontvanger een webmention ontvangt van een reeds bekende Zender, dus met een bekende
sourceentarget, dan moet de ontvangen webmention als bijgewerkt beschouwd worden. Ontvanger zou dan de data van Zender, voor zover hij deze ophaalt/gebruikt, moeten bijwerken. - Als Ontvanger niet langer zijn
target-URL terugziet in de pagina opsource, dan moet hij de webmention als verwijderd beschouwen. - Ook als Ontvanger de pagina op
sourceniet meer kan ophalen (410 Gone), moet hij de webmention als verwijderd beschouwen. - Webmentions moeten idempotent zijn; meerdere dezelfde requests zouden niet meerdere webmentions moeten opleveren.
Implementaties
Prima beschrijving op het blog van Max Böck (hij laat ook via Bridgy berichten binnen een discussie op masto binnenkomen als webmentions).
Inkomend
Naast Bussator is er ook webmentiond. Draait los van Isso en probeert ook niets naar comments te schrijven. Aangezien een comment en een mention twee verschillende dingen zijn, is dat misschien niet eens zo'n slecht idee.
Er is ook webmention.io, zowel hosted als zelf-hosted (code is Ruby).
Uitgaand
Uitgaand is er Telegraph, dat de queueing voor zijn rekening neemt; verder moet je nog steeds een request afschieten per source+target.
Iets soortgelijks, maar met minder overhead (qua uitgaande requests) is webmention.app. Is ook een zelf te draaien command-line van. Allicht handiger, ik hoef zelf dan alleen nog maar de queueing voor mijn rekening te nemen bij het wijzigen van een post (events!), en daarna een losse worker/cronjob het via de commandline laten wegwerken. Het is ook helemaal zelf te hosten.
Andere optie: pushl. Python, kan ook wijzigingen bijhouden.