xtr_webhook.exception ¶
Every error this library raises.
All of them derive from :class:WebhookError, so one except catches anything a
webhook can go wrong with, and a narrower one handles a single cause. Each carries what
went wrong as typed attributes rather than forcing a message to be parsed — and none of
them repeats a secret.
DeliveryError ¶
Bases: WebhookRuntimeError
A receiver answered an outgoing webhook with a status that is not a success.
Raised rather than returned, because a delivery runs inside a message handler: an error is what makes the bus retry it and, once the attempts are spent, keep the message instead of dropping it. A receiver that was merely restarting then costs nothing, and one that stays broken leaves a message to look at.
A delivery nothing answered at all is the client's own TransportError, raised
before this one could be, so the status here is always one a receiver sent.
Attributes:
Record where the webhook was going and what came back.
Parameters:
InvalidArgumentError ¶
Bases: WebhookError, ValueError
A value handed to this library cannot be used: a signature format, an empty secret.
Also a :class:ValueError, so code that already guards against a bad value
catches it without knowing this library exists. It is never an answer to a
request: a webhook refused because of what it carries is a
:class:RejectWebhookError <xtr_webhook.exception.RejectWebhookError>, while
this is a mistake in the configuration to be fixed.
LogicError ¶
Bases: WebhookError, RuntimeError
This library was used in a way that cannot work, whatever the request carries.
A parser asked for a header its format never sends, a signer without a secret to sign with: each is a mistake in the code, so retrying it changes nothing.
RejectWebhookError ¶
RejectWebhookError(status_code: int = 406, message: str = '', headers: Mapping[str, str] | None = None)
Bases: WebhookError
An incoming webhook is refused: it carries the answer the sender is given.
Everything here reaches the sender — the endpoint answers with the status, the headers, and the message as a plain-text body. A sender is not debugged by the receiver, so the message says which check refused it and nothing more: never the values that failed it, nothing an attacker could probe with. The default, 406, says the request was understood and still not acceptable, which is what a wrong signature, a stale timestamp or an unreadable payload all amount to from the sender's side.
Attributes:
-
status_code(int) –What to answer with.
-
headers(Mapping[str, str]) –Headers the answer must carry, empty unless the status needs any.
Refuse the webhook, and record what to answer.
Parameters:
-
status_code(int, default:406) –What to answer with.
-
message(str, default:'') –Why it was refused. The endpoint sends it to the sender as the answer's plain-text body, so name the check that refused the webhook, never the values that failed it.
-
headers(Mapping[str, str] | None, default:None) –Headers the answer must carry.
WebhookRuntimeError ¶
Bases: WebhookError, RuntimeError
Something a webhook depends on failed while it was handled — a receiver that refuses.
The input was fine and the code is fine; the world did not cooperate. Raising one out of a message handler is what makes a message bus retry the delivery and, once it has run out of attempts, keep the message rather than drop it.