Notifications

bidkit.notifications

Verify inbound eBay push notifications (Notification API).

eBay signs every push notification — including the mandatory marketplace-account-deletion notifications — with an ECDSA key identified by the x-ebay-signature request header: a Base64-encoded JSON object {"alg": "ecdsa", "kid": "<key id>", "signature": "<Base64 DER ECDSA>", "digest": "SHA1"}. The matching public key comes from the Notification API's getPublicKey endpoint and should be cached (eBay recommends about an hour).

The signature covers the raw request body bytes — verify before parsing, and never against a re-serialized payload.

Typical endpoint (framework-agnostic)::

verifier = NotificationVerifier(client)

# GET ?challenge_code=... -> endpoint validation
return 200, challenge_response(challenge_code, VERIFICATION_TOKEN, ENDPOINT_URL)

# POST -> notification delivery
if verifier.verify(raw_body, request.headers["x-ebay-signature"]):
    return 204          # acknowledged
return 412              # eBay retries on Precondition Failed

NotificationVerifier

Bases: _VerifierBase

Verifies eBay push-notification signatures using an :class:EbayClient.

Application credentials suffice (the public key is fetched with a client-credentials token on the base scope; a user-token client is scoped down automatically). verify returns False for a bad or malformed signature — respond 412; it raises only on operational failures (key fetch, unsupported key type) — respond 500 and let eBay retry.

AsyncNotificationVerifier

Bases: _VerifierBase

Async counterpart of :class:NotificationVerifier for :class:AsyncEbayClient.

challenge_response(challenge_code, verification_token, endpoint)

The body eBay expects back from the endpoint-validation GET ?challenge_code=….

The hash input order is fixed by eBay: challenge code, then your verification token, then the endpoint URL exactly as registered. Return it as JSON with a 200 status and Content-Type: application/json.