Skip to content

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

DeliveryError(status_code: int, url: str)

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:

  • status_code (int) –

    What the receiver answered with.

  • url (str) –

    Where the webhook was going.

Record where the webhook was going and what came back.

Parameters:

  • status_code (int) –

    What the receiver answered with.

  • url (str) –

    Where the webhook was going.

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.

WebhookError

Bases: Exception

Something a webhook could not be — catch this to catch them all.

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.