eBay Event Notification Platform: Listener SDKs

This March, eBay launched a new event notification platform to push event notifications to developers. Event notifications update applications and users about events on the eBay site, and help reduce the number of API calls an application has to make to retrieve information. The new platform supports multiple payload schema versions, and enables message integrity verification, playback and recovery.

To simplify the processing of eBay notifications, eBay released event notification listener SDKs in Java, Node.js and .NET. These SDKs are intended to bootstrap subscriptions to the latest eBay Notification Platform. 

About eBay’s Event Notification Platform

With event notifications, business events are communicated to all interested subscribers of those event streams.

Platform notifications are triggered by events on the eBay site, such as an item listing ending or an order placement. When subscribing to notifications, developers tell eBay which events they want notifications for and the destination where they should be delivered. Once set up, the notifications are asynchronously pushed to the delivery location.

eBay’s new event notification platform supports JSON format and multiple payload schema versions. One of the use cases – Marketplace Account Deletion is documented at developer.ebay.com/marketplace-account-deletion.

The event streams of our new platform have been documented using the AsyncAPI specification. 

Visit the Notification API documentation page to download the AsyncAPI contracts for the available topics.

How to Subscribe to Event Notifications

To receive the new eBay event notifications, the subscriber needs to set up an endpoint that is able to receive HTTP POST requests. The endpoint must be secure (HTTPS) and should be set up to respond to eBay challenge requests.

When a notification is received, the application needs to respond with one of HTTP status: 200 OK, 201 Created, 202 Accepted or 204 No Content. In case the application does not respond with one of these HTTP statuses, the notification delivery gets marked as a failure. In case of successive notification delivery failures beyond a certain threshold, the endpoint may be marked down or disabled.

Note: Once an endpoint is disabled, an email notification is sent to the alert email associated with the application. Once the issue is resolved, the developer can either wait for the eBay system to detect that it’s back online, or re-enable the endpoint using the Notification API.

A Look at Our Event Notification Listener SDKs

Our primary motivation behind releasing the SDKs is to reduce boilerplate code and abstract key integration functions. For instance, the SDKs provide code to validate messages and to compute the “challenge” response used in the verification process. 

How to Use the SDK

The SDKs incorporate:

1. A deployable application that is generic across topics and can process incoming https notifications;
2. Registration of custom message processors;
3. Declarative OpenAPI powered schema definitions and code generation (Java only); and 
4. Help verify the integrity of the incoming message with built in caches for Public Keys.

Java SDK

1. Clone the repository: github.com/eBay/event-notification-java-sdk
2. Update application.yaml with path to client credentials (required to fetch Public Key from /commerce/notification/v1/public_key/{public_key_id}). 
3. A sample client credentials configuration is available at: ebay-config.yaml
4. Run: mvn spring-boot:run
5. For more information, please refer to: github.com/eBay/event-notification-java-sdk/blob/main/README.md

Node.js SDK

1. Install the package using npm or yarn
   1. npm install event-notification-nodejs-sdk
   2. yarn add event-notification-nodejs-sdk
2. Update config.json with the client credentials
3. Updated the environment in example.js
4. Run the example server using npm or yarn
   npm start
   or,
   yarn start
5. Please refer to example.js for an example of how to set up an express server and use the SDK.
6. For more information, please refer to: https://github.com/eBay/event-notification-nodejs-sdk/blob/main/README.md

.NET SDK

1. Clone the repository: https://github.com/eBay/eBay-Notification-SDK-Dot-Net-Core
2. Update appsettings.json with the path to client credentials (required to fetch Public Key from /commerce/notification/v1/public_key/{public_key_id}). 
3. A sample client credentials configuration is available at: ebay-config.yaml
4. Install and run:
   dotnet build
   dotnetrun
5. For more information, please refer to: https://github.com/eBay/eBay-Notification-SDK-Dot-Net-Core/blob/main/Readme.md 

Note: The client credentials are required to fetch Public Key from /commerce/notification/v1/public_key/{public_key_id}. Learn more about creating application keys.

Our SDK Capabilities

The SDKs have the following capabilities:

Endpoint Registration and Validation

eBay validates a notification endpoint before it can be registered. This process is to confirm the legitimacy of the endpoint and it requires:

1. Notification endpoint – The HTTP endpoint to receive eBay event notifications
2. Verification token – This is a shared secret between the application and eBay to verify the endpoint and is used in the validation algorithm. To avoid misuse of the endpoint, developers should not share the verification token externally. 

The SDKs come with built-in support for algorithms to compute the challenge response required for endpoint registration.

Notification Endpoint Validation 

In order to use the SDK for endpoint validation, developers need to configure the endpoint and verification token in the config.json (NodeJS)/ application.yml (Java)/ appsettings.json (.NET) file.

Once the server is running, the SDK will listen for challenge requests on /webhook.

Endpoint Validation Process

The SDKs come with a ready to use sample webook that responds to challenge requests, which is a series of steps that include integration with Notification API methods.

Listen and Validate Notifications

Once developers have notification endpoints registered, eBay will start sending notifications for the topic(s) developers have subscribed to. 

There are the two important parts of eBay Event Notification:

1. Signature header: Every notification sent by eBay has a X-EBAY-SIGNATURE header that should be used to verify the integrity of the notification payload. The signatures are generated using Elliptic Curve Cryptography.
2. Payload: The notification payload currently is a JSON object that contains the following fields:
   1. metadata.topic: The notification topic
   2. metadata.schemaVersion: The notification schema version
   3. metadata.deprecated: A boolean flag that specifies if the topic has been deprecated
   4. notification.notificationId: The unique notification ID
   5. notification.eventDate: The date on which the event was triggered
   6. notification.publishDate: The data on which the event was published
   7. notification.publishAttemptCount: The notification publish attempts count
   8. notification.data: The notification data (varies based on the topic)

Validate Incoming Notification

These SDKs provide extensibility to subscribe to new topics and plug in custom message handlers making it easy to incorporate business logic without any changes required to the common functions. 

How SDKs validate notifications:

1. Decoding the signature header:
   1. Decode the Base64 signature value
   2. Convert it to a JSON object
2. Use key id from the decoded signature header to fetch the public key (required by the verification algorithm). An LRU cache is used to prevent refetches for the same ‘key’.
3. Compute the hash of the message and verify the message by comparing the hash.
4. On verification success, delegate processing to the registered custom message processor and respond with a 204 HTTP status code.
5. On verification failure, respond back with a 412 HTTP status code. 

While the SDKs are generic for any topic, by default they include the schema definition for MARKETPLACE_ACCOUNT_DELETION notifications.

Process eBay Event Notification

All the SDKs come with an extensible message processor to plugin custom Notification processing logic.

For the MARKETPLACE_ACCOUNT_DELETION use case, simply implement custom logic in:

1. Java SDK: AccountDeletionMessageProcessor.processInternal()
2. NodeJS SDK: accountDeletionMessageProcessor.processInternal()
3. .NET SDK: AccountDeletionMessageProcessor.processInternal() 

Additional message processors can be added to processor.js (NodeJS), EventNotificationConfig.java (Java) or MessageProcessorFactory (.NET)

Conclusion

Our new Notifications platform is designed to meet current and future demands for asynchronous communication to API partners, and we hope our decision to standardize Async API contracts for event notifications will make integrations simple for eBay’s external developer community.

Open source releases are one of the ways we try to engage and involve ourselves with our external developer community. Aside from several popular capabilities we launched in the past with the intention of  simplifying integrations with our platform, all of eBay’s Public API releases include OpenAPI documents that can be used to generate SDKs across technology stacks. 

We hope to be able to continue to facilitate integrations through launches of more capabilities. Our current offerings are available at github.com/ebay.