httk.serve.http.webhook

Hardened outbound HTTPS JSON webhook delivery.

This module is a general-purpose hardened outbound webhook client: strict HTTPS URL parsing (rejecting userinfo, query, fragment, control characters, and non-ASCII after IDNA), DNS resolution filtered to globally-routable addresses only, a connection pinned to a resolved numeric address with TLS SNI carrying the original logical hostname (a DNS-rebinding defence), a bounded HTTP/1.1 request and response cycle with header-size caps and Content-Length / chunked / close-delimited body framing, per-address retry, a concurrency semaphore, and layered connect/read/DNS/total timeouts.

It carries no protocol vocabulary. The Data Space Protocol consumes it through httk.serve.dsp.callbacks, which retains the DSP-facing spelling of these names.

Attributes

WebhookSender

Exceptions

WebhookTransportError

Represent an outbound webhook transport or URL-policy failure.

Classes

PinnedHttpsJsonPoster

Send one HTTPS JSON POST through a validated, pinned socket.

Functions

join_url_path(base_url, path)	Append a fixed absolute path without depending on a trailing slash.
deliver_with_retries(sender, url, document, *[, attempts])	Deliver a document through a sender at most attempts times, requiring a 2xx status.

Module Contents

type httk.serve.http.webhook.WebhookSender = Callable[[str, dict[str, JsonValue]], Awaitable[int]]

exception httk.serve.http.webhook.WebhookTransportError(detail)

Bases: RuntimeError

Represent an outbound webhook transport or URL-policy failure.

Parameters:

detail (str) – Safe detail suitable for local process-delivery state.

detail

httk.serve.http.webhook.join_url_path(base_url, path)

Append a fixed absolute path without depending on a trailing slash.

Parameters:

• base_url (str) – Base URL from an inbound request.

• path (str) – Absolute path beginning with /.

Returns:

Complete URL.

Raises:

ValueError – If the base or fixed path is malformed.

Return type:

str

class httk.serve.http.webhook.PinnedHttpsJsonPoster(*, connect_timeout=5.0, read_timeout=10.0, dns_timeout=5.0, total_timeout=20.0, response_body_limit=65536, max_concurrency=8, allow_private_addresses=False, resolver=None, connector=None)

Send one HTTPS JSON POST through a validated, pinned socket.

DNS resolution occurs inside the concurrency cap and produces the exact numeric socket address dialed for the request. TLS SNI and the HTTP Host header retain the original DNS hostname. The stdlib transport does not consult proxy or environment settings; redirects are not implemented. Both DNS and the complete operation have finite deadlines.

Parameters:

• connect_timeout (float) – Maximum seconds for TCP connect and TLS handshake.

• read_timeout (float) – Maximum seconds for reading a complete response body.

• dns_timeout (float) – Maximum seconds for DNS resolution.

• total_timeout (float) – Maximum seconds from the start of resolution through response completion.

• response_body_limit (int) – Maximum response bytes consumed before rejection.

• max_concurrency (int) – Maximum simultaneous resolution and send operations.

• allow_private_addresses (bool) – Skip global-address filtering when True; the default rejects private targets.

• resolver (_Resolver | None) – Optional test seam that resolves public pinned addresses.

• connector (_Connector | None) – Optional test seam that dials a supplied pinned address.

async httk.serve.http.webhook.deliver_with_retries(sender, url, document, *, attempts=2)

Deliver a document through a sender at most attempts times, requiring a 2xx status.

Parameters:

• sender (WebhookSender) – Awaitable sender returning a peer HTTP status code.

• url (str) – Complete webhook URL passed to the sender.

• document (dict[str, httk.serve.jsondata.JsonValue]) – Plain JSON message document passed to the sender.

• attempts (int) – Maximum number of delivery attempts before failing.

Raises:

WebhookTransportError – If no attempt yields a 2xx acknowledgement.