xtr-webhook
Receive webhooks — verified, replay-bounded, turned into events — and send them signed, in the legacy or the Standard Webhooks format.
Why?
A webhook is an HTTP request from someone who is not a user, so the usual answers do not apply: there is no session to trust, the body is the only thing signed, and a request captured once can be sent again tomorrow. Handling one well means checking it against the right secret, refusing anything outside a window, and getting off the request as fast as possible.
Sending one is the same problem from the other side: sign the exact bytes, say when they were signed, and retry what the receiver refused.
This package does both ends, and turns what arrives into an xtr-remote-event event, so the code that handles it never sees HTTP.
Install
uv add xtr-webhook # signatures, parsers, the endpoint, the events a webhook becomes
uv add xtr-http-client # beside it: sending signed webhooks
The bundle, WebhookBundle, is this package's own. The container it runs on arrives through
xtr-http-kernel, which serves the endpoint and depends on it, so there is
nothing more to install for the bundle. xtr-http-client is neither a
dependency nor an extra: installed beside this package, it is what sends — see Sending.
Quick start
Receiving, with nothing but this package and a bus that handles in process. A controller is given the parser for each type, the secret each is checked against, where to hand on what it read, and the serializer that checks each message can be written before any is handed on:
import asyncio
import hmac
from xtr_http_message import Response, ServerRequest
from xtr_messenger import HandlersLocator, MessageBusConfig, MessageBusFactory, TransportConfig
from xtr_remote_event.messenger import ConsumeRemoteEventMessage
from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
from xtr_webhook.client import RequestParser
from xtr_webhook.controller import WebhookController
SECRET = "the-secret"
BODY = b'{"total": 4200}'
async def consume(message: ConsumeRemoteEventMessage) -> None:
event = message.event
print(f"consumed {event.name} {event.id} {event.payload}")
async def main() -> None:
handlers = HandlersLocator()
_ = handlers.register(ConsumeRemoteEventMessage, consume)
bus = MessageBusFactory(
MessageBusConfig(
transports={"sync": TransportConfig("sync://")},
routing={ConsumeRemoteEventMessage: "sync"},
),
handlers=handlers,
).bus()
serializer = Serializer([PydanticNormalizer()], [JsonEncoder()])
controller = WebhookController({"acme": RequestParser()}, {"acme": SECRET}, bus, serializer)
signed = hmac.new(SECRET.encode(), b"order.paid" + b"evt_1" + BODY, "sha256").hexdigest()
arrived = ServerRequest(
"POST",
"/webhook/acme",
{
"Content-Type": "application/json",
"Webhook-Event": "order.paid",
"Webhook-Id": "evt_1",
"Webhook-Signature": f"sha256={signed}",
},
BODY,
)
answer = await controller.index_action("acme", arrived, Response())
print(f"answered {answer.get_status_code()}")
asyncio.run(main())
consumed order.paid evt_1 {'total': 4200}
answered 202
In an application the endpoint and the controller are the bundle's — see Use in an application.
Receiving
setup(app, kernel) adds the endpoint — no include_router of your own:
from fastapi import FastAPI
from xtr_dependency_injection import Kernel
from xtr_http_kernel import setup
app = FastAPI()
setup(app, Kernel("app"))
The routes file the recipe writes — app.include_router(resources["webhook"]) — is what
registers it: routing is never imported automatically, and deleting the file stops the
application receiving webhooks. The resource is contributed by xtr_webhook.routes, and
including it with a prefix — app.include_router(resources["webhook"], prefix="/hooks") —
moves it to /hooks/webhook/{type}, for an application keeping everything a stranger may
call under one path. Whichever it is, build the URL you hand a sender from the route's name,
"webhook" — a sender that was told a URL keeps sending to it long after the deploy that
changed the path.
| Method | Path | Route name | Resource |
|---|---|---|---|
POST |
/webhook/{type} |
webhook |
webhook |
The route is the webhook resource, which xtr_webhook.routes contributes and the routes file
above registers; its endpoint injects WebhookController, the bundle's service, built from the
configuration below. An application replaces the controller the way it replaces any service:
its own definition of the type outranks the bundle's.
One endpoint serves every sender. The type segment tells them apart: it picks the parser that
reads the webhook and the secret it is checked against, both configuration, so a new sender
needs no new route.
# app/config/packages/webhook.py
from xtr_dependency_injection import configure, env
from xtr_webhook.bundle import RouteConfig, WebhookConfig
@configure
def webhook() -> WebhookConfig:
return WebhookConfig(
routing={
"acme": RouteConfig(secret=env("WEBHOOK_SECRET")),
"stripe": RouteConfig(parser=StripeRequestParser, secret=env("STRIPE_SECRET")),
},
)
Pass a secret through env(...), never as a literal: a placeholder is read only when the
endpoint is built, and no container report prints it.
Routing keys are kept verbatim, dashes included. A type nothing is routed to is answered 404
with No webhook parser found for the type given in the URL. — from the sender's side that URL
does not exist.
What the endpoint answers
| Answer | When |
|---|---|
202 |
the webhook was read, and every event it carried is on the bus |
202 |
the webhook's id is one the configured id_store already remembers: a retry, acknowledged and not handed on again |
404 |
nothing is routed to that type |
406 |
the parser refused it: a signature that does not match, a timestamp outside the window, a body that will not decode, a request the matcher does not claim |
| whatever the refusal carries | a parser raising RejectWebhookError with its own status and headers |
5xx |
something behind the endpoint failed — a bus with nothing to handle the event above all, or an event the bus could not write |
The answer goes out before the events are handled, which is the point: a sender waiting on a handler is a sender that times out and sends the webhook again. The refusal body is plain text naming the check that refused, never the values that failed it.
A 5xx is deliberate rather than tidied away. The sender then sends the webhook again, which is
the only outcome that does not lose what it carried.
A webhook carrying several events is handed on whole or not at all: every event's
ConsumeRemoteEventMessage is written with the serializer — as a bus writing its messages does —
before the first is dispatched. One the serializer refuses, a payload value JSON cannot carry
exactly, raises its error with nothing dispatched, so the sender's retry does not queue the
events before it twice.
Writing a parser
One parser speaks for one sender. Subclass AbstractRequestParser and fill in the two things
that differ per sender — which requests are that sender's, and how to check and read one:
from xtr_http_foundation import (
ChainRequestMatcher,
IsJsonRequestMatcher,
MethodRequestMatcher,
RequestMatcherInterface,
)
from xtr_http_message_contracts import ServerRequestInterface
from xtr_remote_event import RemoteEvent
from xtr_webhook.client import AbstractRequestParser
from xtr_webhook.exception import RejectWebhookError
class AcmeRequestParser(AbstractRequestParser):
def get_request_matcher(self) -> RequestMatcherInterface:
return ChainRequestMatcher([MethodRequestMatcher("POST"), IsJsonRequestMatcher()])
async def do_parse(self, request: ServerRequestInterface, secret: str) -> RemoteEvent:
if request.get_header_line("X-Acme-Token") != secret:
raise RejectWebhookError(406, "Signature is wrong.")
payload = await self.read_json(request)
return RemoteEvent("acme", str(payload["id"]), payload)
The base class does what every parser would otherwise write again, and get wrong in the same
way: the matcher runs before anything is read out of the request, a body that will not decode
comes back as a 406 rather than as a 500, and the two answers are the ones the sender's side
waits for.
await self.read_body(request)returns every byte of the body from its first one, rewinding the stream where it can — a signature covers exactly the bytes that arrived. Reading a body is awaited, so a request whose body is still arriving is read as it comes.await self.read_json(request)decodes the body as a JSON object. An array or a bare value is refused; bytes that are not JSON at all raise, andparse()turns that into the same406. The refusal chains nothing, so no traceback carries the sender's body.do_parsereturns one event, a sequence of them, orNonefor a webhook to accept and ignore — a keep-alive, an event kind this parser does not speak for.Noneand an empty sequence are both answered as unparsable rather than accepted and dropped.- Override
create_successful_response— anasync def, so it can write a body — for a sender that wants something of its own echoed back.create_rejected_responseis the same for a refusal. The response is handed in and given back modified, because an HTTP message is immutable and the endpoint owns the response. - Compare secrets with
hmac.compare_digest, never==.
The matchers come from xtr-http-foundation, so a webhook endpoint
says which requests are its sender's the same way a firewall or a rate limiter does. They are
small and compose: MethodRequestMatcher(["POST", "PUT"]), IsJsonRequestMatcher(),
ChainRequestMatcher([...]) (all must match), and the rest — the path, the host, the port, the
scheme, a header, a query parameter, the address it came from. matches() is awaited, because
a rule may be about the body.
IsJsonRequestMatcher reads the body, not the Content-Type header: a sender that announces
nothing still sent JSON, and one that announces application/json and sent something else did
not. The bundle's own RequestParser does not use it: its matcher is MethodRequestMatcher("POST")
alone, so nothing an unauthenticated sender posts is decoded — the body is read as JSON only once
its signature verified, and one that is not JSON is then refused as Request body is malformed.
Signature formats
RequestParser is this library's own parser, the mirror of its sender, and reads either of two
signature schemes. Once a signature over the body verified, it reads the body as a JSON object —
the event's payload — and builds a RemoteEvent from it, the event's name and id beside it.
SignatureFormat picks which scheme a request must carry:
| Format | Signature header | Signed over | Event name in | Replay bounded |
|---|---|---|---|---|
SignatureFormat.LEGACY |
sha256=<hex> |
event name + id + body | the Webhook-Event header |
no |
SignatureFormat.STANDARD |
v1,<base64> |
<id>.<timestamp>. + body |
the payload's type key |
yes |
SignatureFormat.TRANSITIONAL |
both, space separated | both of the above | both | for the Standard Webhooks entry |
The members are their strings, so a configuration carries "standard" and is understood with
no conversion step. Anything else is refused by SignatureFormat.parse with
InvalidArgumentError.
Both ends must have made the same choice, which is why the sender's configurators and the
receiver's parser each take it. TRANSITIONAL exists so they need not change on the same day: a
receiver accepts whichever scheme it already understands.
Under STANDARD the event name travels in the payload because that scheme's signature covers no
header at all — a name sent as one is a value the receiver cannot trust. A payload with no
type string names no event and is refused. The id is read from the Webhook-Id header, which
both schemes sign.
A genuine body that is JSON but not an object — an array, a string, a number — is answered 406
with Request body is malformed., never repeating the body.
Rotating a secret
The signature header may carry several whitespace-separated entries, one per secret in play, and
any one that verifies is enough. So a rotation is: the sender starts sending both signatures, the
receiver's secret is changed, the sender drops the old one. Each expectation is computed once
rather than per entry, and every comparison is hmac.compare_digest, so the time a refusal takes
says nothing about how much of it was right.
The replay window
A delivery captured once can be sent again tomorrow, so a signed timestamp is held to a window
around now — timestamp_tolerance, 300 seconds by default. Zero or less turns the bound off, for
when clocks that cannot be kept close enough matter more than a replayed capture.
Plainly: a LEGACY signature carries no timestamp, so the window protects only STANDARD and
TRANSITIONAL. Under LEGACY the timestamp header is still sent, but nothing signs it, so
refusing on it would mean trusting a value an attacker sets. The check runs only after a Standard
Webhooks entry verified, which is when the timestamp is known to be the sender's. A timestamp
that does not read as an integer is refused too — a value that cannot be bounded is not accepted
on faith.
A request carrying both schemes is tried Standard-first, so it is replay-bounded whatever order its entries arrive in.
An empty secret
RequestParser raises InvalidArgumentError rather than refusing the request: an empty secret
is this side's configuration, not the sender's doing, so it surfaces as a 5xx. A type with no
secret in its RouteConfig is checked against "", so set one in production — a parser of
your own that verifies nothing would otherwise accept every sender.
Sending
Install xtr-http-client beside this package to send. A webhook goes out as a message, so the delivery is not in the request that caused it, and a refusal is retried by the bus:
from xtr_remote_event import RemoteEvent
from xtr_webhook.messenger import SendWebhookMessage
from xtr_webhook.subscriber import Subscriber
_ = await bus.dispatch(
SendWebhookMessage(
Subscriber("https://example.com/hook", secret),
RemoteEvent("order.paid", "evt_1", {"total": 4200}),
)
)
The event may be of a class derived from RemoteEvent that registered a name — see
xtr-remote-event: it crosses the queue to the worker
that sends it as that class. Over HTTP only its payload is posted — see
Known limitations.
A Subscriber is where the webhook goes and what signs it; the pair travels together because
neither is useful alone. Its secret is kept out of the repr, and an empty one is refused with
InvalidArgumentError — it would still sign, over the empty key, and send perfectly formed
webhooks no receiver can accept.
The message carries the subscriber whole rather than an id, because this library stores no subscribers: the application knows where a webhook goes and says so once, here.
What goes out
A webhook is built by a chain of configurators, each writing one part of the same
OutgoingRequest: HeadersConfigurator the headers naming the event, JsonBodyConfigurator the
payload as the body, HeaderSignatureConfigurator the signature over what the other two wrote.
It runs last, because it signs their output. They are separate because receivers disagree about
all three, so an unusual one means adding or replacing a step rather than the sender.
Transport runs the chain and posts what it built through an HttpClientInterface — the
contract from xtr-http-client-contracts, so whatever stands
behind it does: the client the bundle is told to use, a scoped one, a client wrapped in the guard
below, or a MockHttpClient in a test. It asks the client for the request alone, with no
redirect followed; everything else — how long a delivery may take, above all — is the client's
configuration.
Under LEGACY, RemoteEvent("order.paid", "evt_1", {"total": 4200}):
POST /hook HTTP/1.1
Content-Type: application/json
Webhook-Id: evt_1
Webhook-Timestamp: 1767225600
Webhook-Event: order.paid
Webhook-Signature: sha256=0f8c...
{"total":4200}
Under STANDARD the Webhook-Event header is not sent at all and the name is written into the
payload instead:
POST /hook HTTP/1.1
Content-Type: application/json
Webhook-Id: evt_1
Webhook-Timestamp: 1767225600
Webhook-Signature: v1,dGhlLXNpZ25hdHVyZQ==
{"total":4200,"type":"order.paid"}
Under TRANSITIONAL both headers are sent and Webhook-Signature carries both entries, space
separated.
A payload that already says what it is keeps what it says: the application knows its own events better than their source name does. The payload is copied before the key is added, so dispatching a webhook never edits the dict the caller is still holding.
The body is written by JsonBodyConfigurator(serializer, signature_format) with an
xtr-serializer SerializerInterface, as compact JSON with nothing
reordered — the bytes are the signed message, so two runs over the same payload have to produce
the same ones, and the signer signs exactly those bytes. A payload value JSON cannot carry
exactly — a datetime, a set, a tuple — raises the serializer's NotNormalizableValueError,
unwrapped and never quoting the value, before anything is sent; a payload that contains itself
raises its CircularReferenceError.
Header names and the legacy digest are all configurable:
| Option | Default |
|---|---|
event_header_name |
"Webhook-Event" |
id_header_name |
"Webhook-Id" |
timestamp_header_name |
"Webhook-Timestamp" |
signature_header_name |
"Webhook-Signature" |
signing_algorithm |
"sha256" |
signature_format |
SignatureFormat.STANDARD |
timestamp_tolerance |
300 |
An algorithm this runtime cannot make is refused where it is configured, not at the first delivery. The Standard Webhooks signature is always SHA-256; the scheme fixes it.
Delivery errors and retries
Any answer outside 200-299 raises DeliveryError, carrying .status_code and .url. Nothing is
caught in the handler: the error is what makes the bus retry the delivery and, once the attempts
are spent, keep the message instead of dropping it. Swallowing it would turn every refused
webhook into one silently never sent. How many attempts, and how long between them, is the
messenger transport's — see xtr-messenger.
A delivery nothing answered — a connection refused, a receiver that never replied in time —
raises the client's own TransportError (TransportTimeoutError for time), and is retried the
same way. How long is too long is set on the client: default_options.timeout in the HTTP client
configuration, or a scoped client of its own that http_client names — see
Kernel / bundle.
A redirect counts as refused. Redirects are never followed, whatever the client was built with — the transport asks for none: following one would carry a signed body to an address nobody registered, and would hollow out the guard below.
Private network guard
Opt-in, and off by default. A subscriber URL is usually data — chosen by whoever registered it — so without a guard a webhook is a way to ask this process to fetch an address only this process can see: another service on the same network, an admin port, a cloud provider's metadata endpoint handing out credentials.
The guard is xtr-http-client's NoPrivateNetworkHttpClient, a client wrapping another one —
whichever the transport is given:
from xtr_http_client import HttpClient, NoPrivateNetworkHttpClient
from xtr_serializer import JsonEncoder, PydanticNormalizer, Serializer
from xtr_webhook.server import (
HeadersConfigurator,
HeaderSignatureConfigurator,
JsonBodyConfigurator,
Transport,
)
transport = Transport(
NoPrivateNetworkHttpClient(HttpClient.create()),
HeadersConfigurator(),
JsonBodyConfigurator(Serializer([PydanticNormalizer()], [JsonEncoder()])),
HeaderSignatureConfigurator(),
)
The check runs on what the host resolves to, not on how it is written, so neither a name pointing inwards nor an address spelled unusually gets through. One refused address refuses the whole delivery. The request is then pinned to the address that was checked, so a name whose records change between the check and the connection — a rebinding attack — connects to what was vetted or not at all.
A refusal is the client's TransportError, raised before anything is sent:
Host "<host>" is blocked for "<url>"., or IP "<ip>" is blocked for "<url>". for an address
written out. A retry will not get through either, since nothing about the network changes by
trying again.
With no subnets it refuses the networks only this one can reach — loopback, private,
link-local, carrier-grade NAT, unique-local, multicast, reserved and unspecified alike. Give
subnets to replace that set, and allow_list to open one receiver without opening the network
it sits in. Both take IP networks or single addresses, never hostnames — the check runs on
resolved addresses, and a name could point anywhere by the time it is used.
In the bundle it is no_private_network, and it wraps the client http_client names — the
default one when that is unset:
WebhookConfig(
no_private_network=NoPrivateNetworkConfig(enabled=True, allow_list=("10.1.2.3",)),
)
The guard is on by default: a subscriber's URL is data, so by default no webhook may be sent into
this network. NoPrivateNetworkConfig(enabled=False) turns it off for a receiver that lives
there. Naming subnets or an allow_list while enabled is False is refused rather than
silently ignored — a configuration that looks like protection and is not. Without xtr-http-client
installed nothing is sent, so there is nothing to guard and a receive-only application builds as
it is.
Testing your parsers
xtr_webhook.testing turns a directory of recorded payloads into tests. The helpers come with
the package — they build requests with xtr-http-message, one of its dependencies.
Each *.json fixture has a sibling *.py defining a module-level EXPECTED, the event — or list
of events — it must parse to:
from pathlib import Path
import pytest
from xtr_webhook.testing import ParserCase, assert_parses, parser_cases
@pytest.mark.anyio
@pytest.mark.parametrize(
"case", parser_cases(Path(__file__).parent / "fixtures"), ids=lambda case: case.id
)
async def test_the_parser_reads_every_recorded_payload(case: ParserCase) -> None:
await assert_parses(AcmeRequestParser(), case, secret="the-secret")
parser_cases(fixtures_dir, extension="json") walks the directory recursively and returns a
ParserCase(id, payload, expected) per fixture, sorted by id, so adding a sender's payload to
the directory adds a test. A fixture with no expectation file beside it raises
InvalidArgumentError naming both paths — a payload nobody wrote an expectation for is a test
that silently is not run.
assert_parses(parser, case, *, secret="", headers=None, method="POST") builds the request with
Content-Type: application/json plus whatever headers adds, parses it, and asserts the
events match. Pass the signature headers a real delivery carries through headers.
Nothing here imports pytest, so a fixture directory is usable from any runner.
Security notes
- Subscriber secrets travel inside the queued message body.
SendWebhookMessagecarries the subscriber whole, so the queue storage must be trusted. The bus itself adds nothing to that: its logging middleware records the message type, the transport, the message id, the handler name and the stamps — never the body. - Receiving secrets belong in the environment, passed as
env("..."). ARouteConfig'ssecretis kept out of itsrepr, and a placeholder is resolved only when the endpoint is built. - A
LEGACYsignature is not replay-bounded. UseSTANDARDwhere that matters. - An empty secret signs. Both ends refuse one rather than send or accept webhooks nobody can verify.
- Refusals say as little as the sender needs. Name the check that refused, never the values that failed it.
- Signatures are compared with
hmac.compare_digest. Do the same in a parser of your own. - Nothing follows a redirect, so a signed body cannot be bounced to an address nobody registered.
Known limitations
- Over HTTP only the payload travels. The body is the event's payload, so any receiver reads
it as the JSON object it is, and the name and id travel in the headers. An event of a class
derived from
RemoteEventmay still be sent: only its payload is posted, and the fields its class adds are not. The receiver gets a plainRemoteEvent— its name, its id and the payload. Data a receiver must have goes in the payload, as JSON. - Through the bus the class is kept.
SendWebhookMessagecarries a derived event to the worker as its own class, every field as it left; it is the HTTP request that carries the payload alone. - Under
STANDARDandTRANSITIONALthe payload gains atypekey naming the event, unless it already has one, so the receiver's payload is the sent one with that key added. - The payload is JSON data only. A datetime, a
Decimal, aUUID, bytes, a tuple, a set, an enum member, NaN or infinity, or a key that is not a string is refused at send — convert it first. - A float with an exponent is written with its sign (
1e+16): the same number, other bytes. - Nesting is capped at 200 levels. A deeper payload is refused at send, and a deeper body is
answered
406. Through a serializing bus,SendWebhookMessagerefuses a payload deeper than 198 levels. - Bodies are checked before they are posted, so a large payload costs time to send — keep payloads small.
- The body is written by the application's default serializer, so a
json_indentin its default context indents every body. - A
LEGACYsignature — andTRANSITIONAL's legacy entry — signs the name, the id and the body with nothing between them, so characters can move betweenWebhook-EventandWebhook-Idand the signature still verifies. UseSTANDARDwhere the two matter. - With
timestamp_tolerance=0, a dotted id can lose its tail intoWebhook-Timestamp: the Standard Webhooks entry signsid.timestamp.body, and with the bound off the timestamp is not read as a number. - Under
TRANSITIONALthe event is named by whichever entry verifies — the payload'stypefor the Standard Webhooks entry,Webhook-Eventfor the legacy one. Keeptypeequal to the event's name. - One event class pydantic cannot build refuses every
RemoteEventmessage — see xtr-remote-event's Known limitations.
Use in an application
Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.
- Install —
uv add xtr-webhook; install xtr-http-client beside it to send. The endpoint that receives andWebhookBundleare the package's own, and the container the bundle runs on arrives through xtr-http-kernel, which serves the endpoint. xtr-http-client is what sends — the client, the guard and the client's bundle. Without it, no transport and no send handler are registered, dispatchingSendWebhookMessagefails with the bus's no-handler error, and the guard has nothing to wrap. - Recipe —
uv run xtr-recipes recipes:syncdoes the Activate, Configure and Environment steps below: it listsWebhookBundle, writes a starting<app>/config/packages/webhook.pywith one route,<app>/config/routes/webhook.pyserving the endpoint at its default path, and a freshly generatedWEBHOOK_SECRETin.env. There is no ignore line to write. It prints the steps to callsetupand to name your own types, neither of which a recipe can make for you. - Activate —
WebhookBundle: {"all": True}inBUNDLESin<app>/config/bundles.py, imported fromxtr_webhook.bundle. - Brings along — the remote-event bundle, the messenger bundle through it, the serializer
bundle, whose serializer writes every webhook's body, and the HTTP kernel's bundle, always; the
HTTP client bundle,
http_client, when xtr-http-client is installed. - Configure — needed to receive anything: with no routing the endpoint knows no type and
answers every webhook
404. Routing, header names, the signature format, the client webhooks are sent through and the guard go in<app>/config/packages/webhook.py, a@configurefunction returningWebhookConfig— see Kernel / bundle.<app>/config/routes/webhook.pyimports thewebhookroute resource; move it under a prefix there. A delivery's timeout is the client's, set in<app>/config/packages/http_client.py. - Environment —
WEBHOOK_SECRET, the secret the written route verifies against, read when the endpoint is built; one per sender in practice. The recipe generates one for development: give it to a sender that lets the subscriber choose, or replace it with the one a sender issues, and set the deployment's own in production. - Ignore — nothing.
- Load — call
setup(app, kernel)where the application is built; it adds the endpoint,POST /webhook/{type}. - Remove — drop the
BUNDLESentry, delete<app>/config/packages/webhook.pyand<app>/config/routes/webhook.py, thenuv remove xtr-webhook. - Check —
debug:bundlesshowswebhookandremote_eventaslistedandactive, andhttp_clientwhen xtr-http-client is installed;debug:config webhookshows the resolved routing, header names and signature format.
Kernel / bundle
# app/config/bundles.py
from xtr_webhook.bundle import WebhookBundle
BUNDLES = {WebhookBundle: {"all": True}}
# app/config/packages/webhook.py
from xtr_dependency_injection import configure, env
from xtr_webhook.bundle import NoPrivateNetworkConfig, RouteConfig, WebhookConfig
from xtr_webhook.server import SignatureFormat
@configure
def webhook() -> WebhookConfig:
return WebhookConfig(
signature_format=SignatureFormat.STANDARD,
timestamp_tolerance=300,
http_client="webhook",
no_private_network=NoPrivateNetworkConfig(enabled=True),
routing={
"acme": RouteConfig(secret=env("WEBHOOK_SECRET")),
"stripe": RouteConfig(parser=StripeRequestParser, secret=env("STRIPE_SECRET")),
},
)
http_client names a client of the HTTP client configuration; this one gives webhooks a
timeout of their own. Leave http_client unset to send through the default client, whose
timeout is default_options.timeout — see xtr-http-client.
# app/config/packages/http_client.py
from xtr_dependency_injection import configure
from xtr_http_client.bundle import HttpClientConfig, ScopedClientConfig
@configure
def http_client() -> HttpClientConfig:
return HttpClientConfig(
scoped_clients={"webhook": ScopedClientConfig(scope="https?://", timeout=10)},
)
WebhookConfig:
| Field | Default | What it sets |
|---|---|---|
routing |
{} |
what the endpoint does with each type, by the type in the URL |
signature_format |
SignatureFormat.STANDARD |
the scheme both ends share; a string is accepted |
timestamp_tolerance |
300 |
seconds either side of now a signed timestamp may be; 0 turns the bound off |
signing_algorithm |
"sha256" |
the digest the legacy signature is made with |
event_header_name |
"Webhook-Event" |
where the event's name travels, where the scheme sends one |
id_header_name |
"Webhook-Id" |
where the event's id travels |
timestamp_header_name |
"Webhook-Timestamp" |
where the send time travels |
signature_header_name |
"Webhook-Signature" |
where the signature entries travel |
http_client |
None |
the qualifier of the HttpClientInterface webhooks are sent through — a scoped client's name; None means the default client |
no_private_network |
NoPrivateNetworkConfig() |
whether that client is wrapped in the guard refusing to deliver inwards — on by default — and what counts as inwards |
id_store |
None |
the application's WebhookIdStoreInterface class, built by the container; a webhook id it already remembers (per type) is answered 202 and not handed on again |
id_ttl |
86400 |
seconds an id is remembered, as long as a sender may retry |
RouteConfig(parser=None, secret=""): parser is the class reading that type's webhooks, built
by the container with its dependencies on the first webhook for it; None means the bundle's
own RequestParser, configured by the fields above. Two routes naming one class share one
instance.
The bundle registers the configurator chain, its own parser under the webhook qualifier — so
Annotated[RequestParserInterface, Target("webhook")] resolves to it — every custom parser the
routing names, the endpoint's route loader, and the controller behind it. The chain writes each
payload with the serializer bundle's default SerializerInterface, and the controller checks
each message it is about to dispatch with the same one. The controller gets its
parsers as a service locator, so it never holds the container and a route's parser is built only
when the first webhook for it arrives.
The sending side is registered only when xtr-http-client is installed: the transport, over the
client http_client names — wrapped in NoPrivateNetworkHttpClient when no_private_network is
on — and SendWebhookHandler with it. The handler is registered beside the transport it needs,
so a container never holds a handler it cannot build. The client belongs to the HTTP client
bundle, which builds it, opens its connections when a delivery first needs one, and closes them
with the container.
The zero-config path routes nothing, signs with the legacy scheme under the default header names, and does no I/O at build or boot.
Errors
Everything this library raises derives from WebhookError, and carries what went wrong as typed
attributes rather than forcing a message to be parsed. None of them repeats a secret.
| Error | Raised when | Carries |
|---|---|---|
InvalidArgumentError |
a value cannot be used — an unknown signature format, an empty secret, an unavailable algorithm; also a ValueError |
— |
LogicError |
this library was used in a way that cannot work — a chain that wrote no body, a signer running before the timestamp; also a RuntimeError |
— |
RejectWebhookError |
an incoming webhook is refused; it carries the answer the sender gets | .status_code, .headers |
WebhookRuntimeError |
something a webhook depends on failed while it was handled; also a RuntimeError |
— |
DeliveryError |
a receiver answered an outgoing webhook outside 200-299 | .status_code, .url |
An outgoing webhook nothing answered raises the client's own error instead, unwrapped:
TransportError from xtr-http-client-contracts, or its TransportTimeoutError. The
private-network guard refuses with a TransportError too.
A payload the serializer cannot write raises its NotNormalizableValueError, and a payload that
contains itself its CircularReferenceError — both unwrapped, before anything is sent.
Upgrading
What changes for an application moving to 7.0, and how to keep the old behaviour where that is still possible: Upgrading to 7.0.
Development
Developed in the python-xtr monorepo, under
packages/xtr-webhook; run the commands below from there. The python-xtr-webhook
repository is a read-only copy, so send issues and pull requests to the monorepo.
uv sync
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
License
MIT — see LICENSE.
Metadata
Release files for xtr-webhook 7.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_webhook-7.0.0.tar.gz | 74.2 kB | With provenance | Details for xtr_webhook-7.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_webhook-7.0.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_webhook-7.0.0-py3-none-any.whl |
Total release size: 158.2 kB
Release files / xtr_webhook-7.0.0.tar.gz
| Download URL | xtr_webhook-7.0.0.tar.gz |
|---|---|
| Size | 74.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
347ec5d68615526884f675aa001611d8406f0e2d48d825ecf9223ca8ddcead9a
|
|
BLAKE2b-256 checksum How to use checksums |
0a0a5842ca1977d129182405623013bcf53c3f9fac11a837d970c823ede31333
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / xtr_webhook-7.0.0-py3-none-any.whl
| Download URL | xtr_webhook-7.0.0-py3-none-any.whl |
|---|---|
| Size | 84.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
be82fe13c7113b31d26932203e6f789c2cc63add843df77511a50d3948d7dd49
|
|
BLAKE2b-256 checksum How to use checksums |
af920570851dcc3d54861f910644feb94c95d5946e921cfb5d70d54172d3dc5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for xtr-webhook 7.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_webhook-7.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.