Skip to content

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. None refuses 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

RouteConfig(parser: type[RequestParserInterface] | None = None, secret: str = '')

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. None means the bundle's own configured :class:~xtr_webhook.client.RequestParser, which verifies the signature scheme the bundle's signature_format names.

  • 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 the repr.

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.HttpClientInterface webhooks are sent through — a scoped client of the HTTP client configuration. None means 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.SignatureFormat or 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. None hands on every webhook.

  • id_ttl (int) –

    How many seconds an id is remembered — as long as a sender may retry a webhook.