Skip to main content

notification APIv1.2.0

Notification API

The eBay Notification API enables management of the entire end-to-end eBay notification experience by allowing users to: 

  • Browse for supported notification topics and retrieve topic details

  • Create, configure, and manage notification destination endpoints

  • Configure, manage, and test notification subscriptions

  • Process eBay notifications and verify the integrity of the message payload

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

This overview covers the following topics:

Technical overview

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

Primary methods

The Notification API includes the following resources and methods: 

Tip: See the Notification API reference for more details about the resources and methods listed above.

Primary fields

The primary fields used in the Notification API are:

  • Alert email - The alert email address that is configured for an application.
  • Delivery configuration - The details about the delivery configuration, including the endpoint configured for a destination and its associated verification token.
  • Topic ID - The ID of a supported eBay notification topic to which a subscription can be created and managed.
  • Destination ID - The ID for the configured destination that will receive eBay notifications.
  • Subscription ID - The ID for the subscription to an eBay notification topic. Subscriptions allow user applications to receive notifications and information relevant to their business.
  • Public Key ID – The unique key ID that is used to retrieve the public key from the getPublicKey method. This is retrieved from the X-EBAY-SIGNATURE header that is sent along with eBay push notifications.

Tip: See the Notification API field index for a full list of fields and types used in the Notification API methods.

Business use cases

The following business use cases are outlined in the sections below, which describe the initial notification subscription flow:

Selecting a notification topic

Users can search for and retrieve metadata details for supported eBay notification topics using the getTopic or getTopics methods. The information returned by these methods includes supported schema versions, formats, and the topic IDs.

The following notification topics are currently supported: 

Topic Topic ID Topic Description
Authorization Revocation AUTHORIZATION_REVOCATION When subscribed to this notification topic, developers will receive a push notification for their eBay Developers Program application when a user revokes permissions for that application.
Marketplace Account Deletion MARKETPLACE_ACCOUNT_DELETION When subscribed to this notification topic, developers will receive push notifications for their eBay Developers Program applications when an eBay user has requested that their personal data be deleted and their account closed.

For more information, refer to the eBay Marketplace Account Deletion page.
PLA Campaign Budget Status PLA_CAMPAIGN_BUDGET_STATUS When subscribed to this notification topic, sellers will receive a push notification when their Promoted Listings Advanced (PLA) ad campaign daily budget has been completely exhausted.

Tip: The AsyncAPI playground can be used to visualize AsyncAPI contracts listed in the table above.

Applications can subscribe to any of the topics for a supported schema version and format, limited by the authorization scopes required for subscription to the topic. A topic specifies the type of information to be received and the data types associated with an event.

Note: The topic ID returned by these methods must be input when subscribing to a notification topic, so the data returned by these methods should be retained.

Creating an alert configuration

Before an endpoint destination can be set up to receive notifications, an alert configuration must first be created. The updateConfig method allows users to create a new alert configuration (or update and existing configuration) and specify an alert email for their application.

If an alert configuration has already been created, the getConfig method can be used to retrieve and verify the existing configuration data.

Note: This alert configuration is not topic-based and can be used for multiple subscriptions. As such, only one alert configuration is required per application.

Creating an endpoint destination

Before subscribing to and receiving eBay notifications, users must prepare their endpoint destinations to receive a challenge code from eBay, and then use this challenge code to validate the legitimacy of the endpoint URL. eBay needs to verify that the user owns/has access to the provided endpoint URL.

The createDestination method is used to begin the process, at which point the user must specify the destination endpoint and verification token. Immediately after the developer provides and saves an endpoint URL and a verification token, eBay will send a challenge code to that URL in the form of a GET call. This GET call will use this format:

GET https://<callback_URL>?challenge_code=123

Note: The challenge_code query parameter value will be unique for the request. The provided endpoint URL should use the HTTPS protocol, and it should not contain an internal IP address or localhost in its path.

Upon receiving this unique challenge code, the endpoint must be set up to hash together the challenge code, verification token, and endpoint URL, and then reply back to eBay with a 200 OK and the hashed value through a challengeResponse field in JSON format: 

{
"challengeResponse":"52161ff4651cb71888801b47bae62f44d7f6d0aab17e70d00f64fc84368ca38f"
}

The content-type header for this response must be set to application/json and the three parameters must be hashed in the following order, or the verification will fail:

challengeCode + verificationToken + endpoint

eBay will verify the hexadecimal string before the endpoint can be officially subscribed to notifications. The endpoint and verification token are values specific to the destination, but the challenge code variable will come from eBay in the form of the challenge_code query parameter, which is randomly generated and unique to the request.

Note: The verification token must be between 32 and 80 characters. Allowed characters include alphanumeric characters, underscores (_), and hyphens (-); no other characters are allowed.

Code snippets in Node.js, Java, Python, and PHP for computing the challenge response are provided below.

Node.js

const hash = createHash('sha256');
hash.update(challengeCode);
hash.update(verificationToken);
hash.update(endpoint);
const responseHash = hash.digest('hex');
console.log(new Buffer.from(responseHash).toString());

Java

MessageDigest digest = MessageDigest.getInstance("SHA-256");
digest.update(challengeCode.getBytes(StandardCharsets.UTF_8));
digest.update(verificationToken.getBytes(StandardCharsets.UTF_8));
byte[] bytes = digest.digest(endpoint.getBytes(StandardCharsets.UTF_8));
System.out.println(org.apache.commons.codec.binary.Hex.encodeHexString(bytes));

Python

m = hashlib.sha256(challengeCode+verificationToken+endpoint);
print(m.hexdigest());

PHP

$hash = hash_init('sha256');
hash_update($hash, $challengeCode);
hash_update($hash, $verificationToken);
hash_update($hash, $endpoint);
$responseHash = hash_final($hash);
echo $responseHash;

Subscribing to a notification topic

After users have tested their code and destination endpoint, and feel confident that the endpoint is ready to process and reply back to eBay's challenge code, a subscription to an eBay notification topic can be established.

The createSubscription method is used to create a subscription. Subscriptions allow applications and users to receive the information relevant to their businesses.

Each application/user and topic-pairing to a subscription should have a 1:1 cardinality. Create a new subscription for a new version of a notification, and when migration to the new version has been completed, the old subscription may be deleted. Users can create the subscription in disabled mode, test it (see the test method), and when everything is ready, enable the subscription (see the enableSubscription method).

When creating a new subscription, it is important to include the appropriate scopes for the type of subscription:

  • For application-based subscriptions, the following scope must be included and the OAuth token must be created using the client credentials grant flow:
    https://api.ebay.com/oauth/api_scope

  • For user-based subscriptions, the following scope must be included and the OAuth token must be created using the authorization code grant flow:
    https://api.ebay.com/oauth/api_scope/commerce.notification.subscription

Note: If an application or user is not authorized to subscribe to a topic, for example, if the authorization does not include the list of scopes required for the topic, an error code of 195011 is returned.

Similarly, when retrieving subscriptions for a topic using the getSubscription or getSubscriptions method, the appropriate grant flow and scope must be used in order to view the associated application-based or user-based subscriptions for a topic. For example, if the getSubscriptions method was called using the client credentials grant flow, only the application-based subscriptions for the topic would be returned. Conversely, if the authorization code grant flow was used to create the OAuth token instead, only the user-based subscriptions for that topic would be returned.

Validating eBay push notifications

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.