notification APIv1.0.0

Notification API

The eBay Notification API allows third-party developers and applications to process eBay notifications and verify the integrity of the message payload.

This overview covers the following topics:

For more information about using RESTful APIs, see Using eBay Restful APIs.

Technical overview

The eBay Notification API allows users to process notifications using the primary method and fields listed in the sections that follow.

Primary methods

Currently, the only method used for the Notification API is the getPublicKey method. This method allows users to retrieve a public key by specifying a public key ID. The public key can then be used to perform validation of notifications sent out by eBay.

Primary fields

The primary fields used in the getPublicKey method are:

  • Public Key ID – The unique key ID that is used to retrieve the public key. This is retrieved from the X-EBAY-SIGNATURE header that is sent along with eBay push notifications.
  • Key – The public key that is returned for the specified public key ID. This is retrieved from the getPublicKey Notification API method.

Business use cases

Users who sign up to receive HTTP push notifications from the eBay notification platform receive push notifications that include an X-EBAY-SIGNATURE header along with the notification payload. This header is a Base64-encoded, packed header that uses the following structure:

{
"alg":"{ECDSA}",
"kid":"{public key ID}",
"signature":"{signature}",
"digest":"{SHA1}"
}

After the notification payload and header are received, users should verify that the notification actually came from eBay. The notification can be validated using the Event Notification SDKs, or by completing the manual validation procedure outlined below.

Event Notification SDKs

eBay has created SDKs to verify the validity of each notification.

These SDKs are intended to bootstrap subscriptions to eBay Notifications. These SDKs incorporate:

  1. Decoding the signature header from the notification to retrieve the public key ID ("kid").
  2. Completing a cache-enabled call to the getPublicKey Notification API method to retrieve the public key.
  3. Verifying the signature against the notification payload.
  4. Delegating the payload to the processing logic for the topic (if the signature is verified) and returning an HTTP status of 200 OK. If the signature verification fails, an HTTP status of 412 Precondition Failed is returned.

Note: Refer to the README files in the SDKs for more details.

Manual validation

The following procedure can be used to manually process the notification and validate the message payload integrity: 

  1. Use a Base64 function to decode the X-EBAY-SIGNATURE header and retrieve the public key ID and the signature.
  2. Call the getPublicKey Notification API method, passing in the public key ID ("kid") retrieved from the decoded signature header.
  3. Initialize the cryptographic library to perform the verification with the public key that is returned from the getPublicKey method.

Note: The verification is a function of the signature, payload, and public key.

Here is a Java example of the verification process:

EncodedKeySpec publicKeySpec = new X509EncodedKeySpec(Base64.getDecoder().decode{public key});
java.security.PublicKey publicKey = KeyFactory.getInstance("EC").generatePublic(publicKeySpec);
Signature sig = Signature.getInstance{SHA1 with ECDSA};
sig.initVerify{public key};
sig.update(messagePayload.getBytes());
sig.verify(Base64.getDecoder().decode{signature value from X-EBAY-SIGNATURE header});

API restrictions

This section outlines the restrictions for use of the eBay Notification API.

Sandbox vs. Production data

The data in the eBay Sandbox environment is static. It can be limited in scope and quantity, and is sometimes simulated or mock data. As a result, you should not depend on data in the Production environment to have the same limitations. Use good coding practices to anticipate the wider range and variability of data that your application is likely to encounter.