Skip to main content

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, refer to Using eBay Restful APIs.

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: Refer to 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.
  • Filter ID - The ID for the filter associated with a subscription. Filters allow user applications to receive notifications only when they match a provided criteria.
  • 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: Refer to 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:

Select 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:

Note: To receive any of these push notifications, you have to be subscribed to the Topic.

Topic Topic ID Topic Description
Authorization Revocation AUTHORIZATION_REVOCATION

This notification is sent to a developer when a user revokes permissions for their eBay Developers Program application.

Item Availability ITEM_AVAILABILITY

This notification is sent to a developer when a fixed price item's availability type changes.

Availability types include: AVAILABLE, UNAVAILABLE, and TEMPORARILY_UNAVAILABLE.

Note: Currently, this topic is available for eBay Partner Network (ePN) partners in all marketplaces except for the following: CA, AU, HK, SG, MY, and PH.
Item Price Revision ITEM_PRICE_REVISION

This notification is sent to a developer when a fixed price item's price changes.

Note: Currently, this topic is available for eBay Partner Network (ePN) partners in all marketplaces except for the following: CA, AU, HK, SG, MY, and PH.
Marketplace Account Deletion MARKETPLACE_ACCOUNT_DELETION

This notification is sent to a developer 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.
Priority Campaign Strategy Budget Status PLA_CAMPAIGN_BUDGET_STATUS

This notification is sent to sellers when their Promoted Listings priority strategy ad campaign (formerly Promoted Listings Advanced (PLA)) daily budget has been completely exhausted.
Priority Listing Revision PRIORITY_LISTING_REVISION

This notification is sent to sellers when their Priority Listing has been revised.

Note: Currently, this topic is available for eBay Partner Network (ePN) partners in all marketplaces except for the following: CA, AU, HK, SG, MY, and PH.
Seller Customer Service Metric Rating SELLER_CUSTOMER_SERVICE_METRIC_RATING

This notification is sent to sellers to inform them about critical changes to their customer service metrics performance (this includes proactive warnings when their service metrics are trending towards 'very high'). The payload for this notification is similar to the Analytics API getCustomerServiceMetric method.
Seller Standards Profile Metrics SELLER_STANDARDS_PROFILE_METRICS

This notification is sent to sellers to inform them about critical changes to their seller performance metrics and seller level (this includes proactive warnings when their performance metrics are close to the threshold that could change the seller's standard level). The payload for this notification is similar to the Analytics API findSellerStandardsProfiles method.

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.

Create 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.

Create 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;

Subscribe 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.

Create a subscription filter for a topic

Once a user has created an endpoint destination and subscribed to a notification topic, a subscription filter can be added to the subscription that allows applications to only receive notifications that match the provided criteria; notifications that do not match will not be sent to the destination.

Note: Not all topics are able to have filters applied to them. Use the getTopic and getTopics requests to determine if the selected topic is filterable. Filterable topics have the boolean filterable set to true in the response.

The createSubscriptionFilter method is used to create a subscription filter. Make sure the subscription filter adheres to the following:

  • A filter request must be for an enabled subscription owned by the user

  • The subscription must be to a topic that is filterable. Use the getTopic and getTopics requests to determine if the selected topic is filterable. Filterable topics are indicated with the boolean filterable set to true in the response. If the topic is not filterable, the filter will be rejected, become DISABLED, and return a 195032 error code

  • The filterSchema value provided must be a valid JSON Core document (version 2020-12 or later) and must describe the subscription's notification payload such that it supplies valid criteria to filter the subscription's notifications. If the supplied JSON specifies a field that does not exist in the notifications for a topic, the filter will be rejected, become DISABLED, and return a 195033 error code

Initially, when the createSubscriptionFilter request has been made, if the request has a valid JSON body, a 201 Created is returned and the filter will be in PENDING state while it undergoes review. If the filter is approved, it will move from the PENDING status to the ENABLED status. You can find the status of a filter using the getSubscriptionFilter method. A getSubscription response will now show the filterId associated with the subscription.

Validate 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});

Important! The public key value retrieved from the getPublicKey method should be cached for a temporary — but reasonable — amount of time (e.g., one-hour is recommended.) This key should not be requested for every notification since doing so can result in exceeding API call limits if a large number of notification requests is received.

API restrictions

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

The Commerce Notification API events below require scope https://api.ebay.com/oauth/api_scope/buy.item.stream and it is only available to the approved ePN partners.

  • ITEM_AVAILABILITY
  • ITEM_PRICE_REVISION

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.