Webmention

Discover a Webmention Endpoint

Webmention endpoint discovery is useful if you want to know if you can send webmentions to a site or if you want to send a webmention to a site.

You can discover if a URL has an associated webmention endpoint using the discover_webmention_endpoint function:

indieweb_utils.discover_webmention_endpoint(target: str) → WebmentionDiscoveryResponse[source]

Return the webmention endpoint for the given target.

Parameters:: target (str) – The target to discover the webmention endpoint for.
Returns:: The discovered webmention endpoint.
Return type:: str

import indieweb_utils

target = "https://jamesg.blog/"

webmention_endpoint = indieweb_utils.discover_webmention_endpoint(
    target
)

print(webmention_endpoint) # https://webmention.jamesg.blog/webmention

Raises:

TargetNotProvided – Target is not provided.
WebmentionEndpointNotFound – Webmention endpoint is not found.
UnacceptableIPAddress – Endpoint does not connect to an accepted IP.
LocalhostEndpointFound – Discovered endpoint is equal to localhost.

If successful, this function returns the URL of the webmention endpoint associated with a resource. In this case, the message value is a blank string.

If a webmention endpoint could not be found, URL is equal to None. In this case, a string message value is provided that you can use for debugging or present to a user.

Send a Webmention

To send a webmention to a target, use this function:

indieweb_utils.send_webmention(source: str, target: str, me: str | None = None, code: str | None = None, realm: str | None = None, target_webmention_endpoint: str | None = None) → SendWebmentionResponse[source]

Send a webmention to a target URL.

Parameters:

source (str) – The source URL of the webmention.
target (str) – The target URL to which you want to send the webmention.
me (str) – The URL of the user.
code (str) – An authorization code that grants access to the Webmention source (optional). See https://indieweb.org/Private-Webmention#Auth_Code_Generation for more information.
realm (str) – A unique value for the intended recipient or audience (optional). See https://indieweb.org/Private-Webmention#Auth_Code_Generation for more information.
target_webmention_endpoint – The webmention endpoint of the target URL. If this value is provided, Webmention endpoint discovery on the target will be skipped.

Returns:

The response from the webmention endpoint.

Return type:

SendWebmentionResponse

Example:

import indieweb_utils

response = indieweb_utils.send_webmention(
    source="https://example.com",
    target="https://example.example.com/post/1",
    me="https://test.example"
)

Raises:

TargetIsNotApprovedDomain – Target is not in list of approved domains.
GenericWebmentionError – Generic webmention error.
CouldNotConnectToWebmentionEndpoint – Could not connect to the receiver’s webmention endpoint.

This function returns a SendWebmentionResponse object with this structure:

class indieweb_utils.SendWebmentionResponse(title: str, description: str, url: str, status_code: int | None, headers: List[indieweb_utils.webmentions.send.Header])[source]