xtr_webhook.bundle ¶
The xtr-dependency-injection bundle for xtr-webhook.
NoPrivateNetworkConfig
dataclass
¶
NoPrivateNetworkConfig(enabled: bool = True, subnets: tuple[str, ...] | None = None, allow_list: tuple[str, ...] = ())
Whether the client webhooks are sent through refuses to deliver into a private network.
On by default: a webhook's URL is the subscriber's to choose, so by default
none may point into this network. It wraps that client in
:class:~xtr_http_client.NoPrivateNetworkHttpClient, which checks what
every destination resolves to before anything is sent.
Attributes:
-
enabled(bool) –Whether outgoing webhooks are vetted at all.
-
subnets(tuple[str, ...] | None) –The networks to refuse, in CIDR notation, replacing the default.
Nonerefuses every address that is not globally routable — loopback, private, link-local, carrier-grade NAT, unique-local, multicast, reserved and unspecified alike. -
allow_list(tuple[str, ...]) –Networks or single addresses exempt from the refusal. Addresses only, never hostnames: the check runs on resolved addresses, and a name could point anywhere by the time it is used.
RouteConfig
dataclass
¶
What the endpoint does with webhooks of one type.
Attributes:
-
parser(type[RequestParserInterface] | None) –The class reading this type's webhooks, built by the container with its dependencies on the first webhook for it.
Nonemeans the bundle's own configured :class:~xtr_webhook.client.RequestParser, which verifies the signature scheme the bundle'ssignature_formatnames. -
secret(str) –What this type's webhooks are verified against. Pass it through the container's
env("...")placeholder, never as a literal: a placeholder is read only when the endpoint is built, and no container report prints it. It must be set in production — with an empty value, depending on the parser, requests from any sender are accepted or every request is rejected. Kept out of therepr.
WebhookBundle ¶
Bases: Bundle[WebhookConfig]
Wires the endpoint's controller and the sender's chain to the container.
load_extension ¶
load_extension(config: WebhookConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None
Register the configurators, the parser, the controller and the sending side.
The format is converted once, here: the configurators and the parser take a member, and every factory below is handed the same one.
Without xtr-http-client nothing is sent, so the private-network guard — on by default — has nothing to wrap and is simply not built: a receive-only application builds as it is.
WebhookConfig
dataclass
¶
WebhookConfig(http_client: str | None = None, no_private_network: NoPrivateNetworkConfig = NoPrivateNetworkConfig(), event_header_name: str = 'Webhook-Event', id_header_name: str = 'Webhook-Id', timestamp_header_name: str = 'Webhook-Timestamp', signature_header_name: str = 'Webhook-Signature', signing_algorithm: str = 'sha256', signature_format: SignatureFormat | str = SignatureFormat.STANDARD, timestamp_tolerance: int = 300, routing: Mapping[str, RouteConfig] = _no_routes(), id_store: type[WebhookIdStoreInterface] | None = None, id_ttl: int = 86400)
Values the bundle builds the endpoint's and the sender's services from.
Buildable with no arguments: the zero-config path routes nothing, signs with the legacy scheme under the default header names, and sends through the application's default HTTP client.
Attributes:
-
http_client(str | None) –The qualifier of the :class:
~xtr_http_client_contracts.HttpClientInterfacewebhooks are sent through — a scoped client of the HTTP client configuration.Nonemeans the default, unqualified one. -
no_private_network(NoPrivateNetworkConfig) –Whether that client is wrapped in a guard refusing to deliver into a private network, and what counts as one.
-
event_header_name(str) –The header the event's name travels in, where the signature scheme sends one.
-
id_header_name(str) –The header the event's id travels in.
-
timestamp_header_name(str) –The header the send time travels in.
-
signature_header_name(str) –The header the signature entries travel in.
-
signing_algorithm(str) –The digest the legacy signature is made with.
-
signature_format(SignatureFormat | str) –The signature scheme both ends must share — a :class:
~xtr_webhook.server.SignatureFormator the string one carries. Validated here; readers convert with :meth:SignatureFormat.parse <xtr_webhook.server.SignatureFormat.parse>. -
timestamp_tolerance(int) –How many seconds either side of now an incoming signed timestamp may be. Zero turns the replay bound off.
-
routing(Mapping[str, RouteConfig]) –What the endpoint does with each webhook type, by the type in the URL. Keys are kept verbatim — dashes too.
-
id_store(type[WebhookIdStoreInterface] | None) –The application's class remembering the ids of the webhooks already taken, built by the container. A webhook id it remembers is acknowledged with 202 and not handed on again.
Nonehands on every webhook. -
id_ttl(int) –How many seconds an id is remembered — as long as a sender may retry a webhook.