Working with Platform Notifications

Platform notifications are triggered by events on the eBay site, such as the ending of a listing or the creation of a transaction. Notifications are SOAP messages about events on the eBay site, sent to subscribing applications.

You subscribe to notifications by setting your application's platform notification preferences, which tell eBay which events you want notification of and the URLs or email addresses to which you want the notifications delivered. Once you're subscribed, eBay Platform Notifications asynchronously pushes the notifications to your delivery location.

Subscribing to notifications is a good way to reduce the number of times your application has to execute transaction retrieval, feedback, and other routine API calls. Notifications do not count as API calls, and do not count against your daily API call limit.

You should use API calls to confirm the data received using notifications. For example, if you have subscribed to AuctionCheckoutComplete notification, ensure that you have set up periodic polling of GetOrders.

Your application should respond to notifications with a standard HTTP status of 200 OK. Absent this response to a notification, eBay will attempt redelivery, but after a significant number of unacknowledged notifications, eBay may stop sending notifications to your application.

Platform notifications are not identical to the email messages that buyers and sellers might get when an item is listed, bid on, or purchased, though they may contain some of the same data.

For a brief demonstration of a user subscribing to and receiving notifications, see the API flow tutorial "Getting Notifications":

http://developer.ebay.com/DevZone/XML/docs/HowTo/Notifications/Notifications_listing.html

In this chapter:

Notifications for Buyers and Sellers

Some notifications provide information that is specifically useful to sellers only, and these are restricted to sellers. Other notifications provide information that is useful to buyers only, or to both buyers and sellers.

See NotificationEventTypeCodeType for a description of each notification event and to whom it applies.

Subscribing to Platform Notifications

Your application can subscribe to notifications using SetNotificationPreferences (see SetNotificationPreferences in the Call Reference). See NotificationEventTypeCodeType for the kinds of events to which an application can subscribe.

You can check existing preferences with GetNotificationPreferences (see GetNotificationPreferences in the Call Reference).

Your platform notification usage can be monitored with GetNotificationsUsage. For more information on GetNotificationsUsage and how to use it to troubleshoot notification problems, see GetNotificationsUsage in the Call Reference.

Basic Requirements

The Compatible Application Check is not a requirement for using Platform Notifications.

Your application needs to be able to receive SOAP messages at a notification delivery URL or email address of your choice. You can then parse the SOAP message for the XML content contained in the SOAP envelope.

Notification Delivery URL Requirements

Notifications are delivered by an HTTP post to URLs or by a SMTP message to email addresses that you specify in your notification preferences.

A valid notification delivery URL begins with http://or https:// and is well formed. Use ApplicationDeliveryPreferences.ApplicationURL to specify a URL to receive notifications for your application. Notifications will not be sent to any URL(s) if ApplicationDeliveryPreferencesType.ApplicationEnable is set to Disable.

Notification delivery URLs can include query string variables. For example, the following URLs are valid:

http://my_hostname.com/cgi/my_notifications.asp

https://my_hostname.com/cgi/my_notifications.asp?myvar1=45&myvar2=123456789

Note: We recommend that you specify URLs that are currently functional. That is, your application should be ready to receive and respond to SOAP messages that are sent to these URLs. The subscription request will succeed if the delivery URLs are not functional URLs at the time the subscription request is made. However, if eBay begins sending notifications to the URLs and your application does not respond with a standard HTTP status 200 OK, eBay will interpret the lack of response as a notification failure. If a significant number of consecutive notifications fail, eBay may stop sending notifications for events associated with your AppId. If this occurs, please make sure the URLs are functional and then contact Developer Technical Support to reinstate your notification delivery.

Specifying Multiple Notification URLs

You can specify up to 25 notification URLs for an application. You define settings for up to 25 notification URLs (including the URL name in DeliveryURLName) in separate ApplicationDeliveryPreferences.DeliveryURLDetails containers in your SetNotificationPreferences request. You associate a user token with a notification URL (or up to 25 URLs) by using the token in a SetNotificationPreferences request that specifies the URL name in SetNotificationPreferencesRequest.DeliveryURLName. For multiple URLs that have been defined in ApplicationDeliveryPreferences.DeliveryURLDetails, use comma-separated format to enable them for a user token in SetNotificationPreferencesRequest.DeliveryURLName.

Use ApplicationDeliveryPreferences.ApplicationURL to specify a default URL to receive notifications for your application. Notifications will not be sent to any URL(s) if ApplicationDeliveryPreferencesType.ApplicationEnable is set to Disable.

Notifications for Fixed-Price Listings with Variations or Multiple Quantities

Because you can edit multiple-item, fixed-price listings, even after one or more of the items in that listing has been sold, sellers or buyers of items in a multiple-quantity listing can get a snapshot of the listing as it was at the time of a given purchase by invoking GetItem with a Transaction ID as input.

Sellers of an item are allowed to view all transactional snapshots of the listing, whereas buyers can only view the transactional snapshots for which they are the successful buyer. Past transactional views of an item are available for up to 90 days from the date the transaction took place.

You can set a transaction event to trigger your notifications, or you can set an event related to the entire listing to trigger your notifications. If you're using item transaction snapshot data, Listing Status may report an Active status because the listing was Active on the transaction date, but the listing may actually have Ended.

Receiving Platform Notifications

After notification delivery is enabled for your application, eBay will send notifications related to listings that your application has submitted using AddItem, RelistItem, and ReviseItem. When your application uses one of these calls, eBay identifies the application by its AppId (via the user token). The application's AppId is then associated with the listing. This is how eBay knows which application to notify when transactional or feedback events occur in relation to the listing.

Also see Specifying Multiple Notification URLs.

Responding to Notifications

When a notification is sent, your application needs to respond with a standard HTTP status 200 OK. If you do not respond, eBay records the notification attempt as a failure, and the system does not resend the message. However, the database record for the event will still exist in the eBay system, so you can retrieve the event information by using the transaction-retrieval and feedback API functions (for example, GetSellerEvents).

If a significant number of notification failures occur consecutively (usually due to a problem with your delivery URLs or your application' ability to respond), eBay may stop sending notifications for events associated with your application's AppId.

SOAP Message Fields

Notifications are sent as SOAP messages. Each SOAP message consists of:

The SOAP header contains the notification signature that is used for security, and the SOAP body contains the actual event.

HTTP Header

Each SOAP message contains an HTTP header that consists of the following pieces of information:

This example shows an HTTP header for an EndOfAuction notification. This customer provided eBay with the URL my_hostname.com/cgi/my_notifications.asp.

Figure: EndOfAuction Notification Header Example
POST: /cgi/my_notifications.asp
PROTOCOL: HTTP/1.1
HOST: my_hostname.com
CONTENT_TYPE: text/xml; charset="utf-8"
CONTENT_LENGTH: 1252
SOAPACTION: "HTTPS://developer.ebay.com/notification/EndOfAuction"

SOAP Message Header: Notification Signature

Each notification message contains a notification signature in the SOAP header for third-party application security. Your application should use the signature for message authentication to make sure the message was actually sent by eBay and that the notification signature was not copied by another party.

The notification signature is an MD5 hash signature that is generated using the following formula of concatenated strings, where DevId, AppId, and CertId are your application's Production Keys:

eBayTime + DevId + AppId + CertId

This hash is then Base64-encoded to reduce its length.

To have your application authenticate the signature:

  1. Compute the MD5 hash using a standard routine, such as Microsoft crypto API, or OpenSSL open source.
  2. You can find more information about these routines at:

    http://www.openssl.org/

  3. Convert the hash to Base64 encoding.
  4. Compare the inputs in the notification signature to their actual values.

The eBayTime part of the signature should match the value of the Timestamp element in the SOAP message. Your application should check to make sure that the value of eBayTime is within 10 minutes of the actual time in GMT. The following code, written in C#, shows how to validate the notification hash:

Figure: Example of How to Validate the Notification Hash (C#)
private bool CheckSignature(DateTime TimeStamp) {
  const string AppId = "myproductionappid";
  const string DevId = "myproductiondevid";
  const string AuthCert = "myproductionauthcert";
  // Converts the TimeStamp back to universal time, because in .NET, XML schema time values
  // are converted to local time
  // If you are retrieving the time stamp directly from the XML body of the notification
  // message, you would not need to convert it.
  string sig = TimeStamp.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ") + DevId +
      AppId + AuthCert;
  byte[] sigdata = System.Text.Encoding.ASCII.GetBytes(sig);
  System.Security.Cryptography.MD5 md5 =
      new System.Security.Cryptography.MD5CryptoServiceProvider();
  string md5Hash = System.Convert.ToBase64String(md5.ComputeHash(sigdata));
  return (mRequesterCredentials.NotificationSignature ==
      md5Hash DateTime.Now.Subtract(TimeStamp).Duration().TotalMinutes <= 10);
}

SOAP Message Body

The following notification-related fields of AbstractResponseType are or can be returned in the body of a notification: NotificationEventName, RecipientUserID, EIASToken. (NotificationSignature is returned in the header.) See AbstractResponseType for descriptions of these fields.

Each SOAP message body contains a top-level element, the name of which is the call that was used to generate the data, with the word Response at the end. For example, the element name for the EndOfAuction call is GetItemTransactionsResponse. This element contains one attribute to specify the namespace: xmlns="urn:ebay:apis:eBLBaseComponents". Child elements include some elements common to all notifications, such as Timestamp, which specifies the time the notification was sent. Other child elements are specific to the notification being sent. In the EndOfAuction notification, the Item element contains most of the data for the notification.

Notification Payloads

The content, or "payload," of a notification is equivalent to the response from a corresponding API call.

With SetNotificationPreferences, you can use the PayloadVersion field to specify the API version for all notifications for the calling application. With GetNotificationPreferences, this field contains the API version for all notifications for the calling application.

See the following table for a list of notifications and their corresponding API calls.

Table: API Call Payloads for Notifications
Notification API Call Payload
AskSellerQuestion Notification
AuctionCheckoutComplete Notification
BestOffer Notification
BestOfferDeclined Notification
BestOfferPlaced Notification
BidPlaced Notification
  • GetItem with default detail level
BidReceived Notification
  • GetItem with default detail level
BulkDataExchangeJobCompleted Notification
CheckoutBuyerRequestsTotal Notification
Checkout Notification
CounterOfferReceived Notification
eBay Buyer Protection Notifications
EndOfAuction Notification
Feedback Notification
FeedbackLeft Notification
FeedbackReceived Notification
FeedbackStarChanged Notification
FixedPriceTransaction Notification
INR (ItemNotReceived) Notifications
ItemAddedToBidGroup Notification
  • GetItem with default detail level
ItemAddedToWatchList Notification
  • GetItem with default detail level
ItemClosed Notification
  • GetItem with default detail level
ItemListed Notification
  • GetItem with default detail level
ItemLost Notification
  • GetItem with default detail level
ItemRemovedFromBidGroup Notification
  • GetItem with default detail level
ItemRemovedFromWatchList Notification
  • GetItem with default detail level
ItemRevised Notification
  • GetItem with default detail level
ItemSold Notification
ItemUnsold Notification
  • GetItem with default detail level
ItemWon Notification
  • GetItem with default detail level
MyMessages Notification
  • GetMyMessages with ReturnHeaders or ReturnMessages detail level
OutBid Notification
  • GetItem with default detail level
eBay Return Notifications
SecondChanceOffer Notification
  • GetItem with default detail level
BuyerResponseDispute Notification
SellerClosedDispute Notification
SellerOpenedDispute Notification
SellerRespondedToDispute Notification
TokenRevocation Notification
WatchedItemEndingSoon Notification

Receiving Notifications by Email

You can specify that you want to receive notifications by email, rather than posted to a server. To specify a default email URL for notifications, pass ApplicationDeliveryPreferencesType in SetNotificationPreferences. In the ApplicationDeliveryPreferencesType, set ApplicationURL to a URL that starts with mailto:// or mailto: followed by a valid email address. For example, specify:

mailto://someone@xyz.com

mailto:anyone@acme.com

Use the same mechanism if you are specifying muliple locations for notifications (see Specifying Multiple Notification URLs).

Testing Platform Notifications

The Platform Notifications feature is supported in the Sandbox. Notifications are generated when certain events occur. To test the Platform Notifications feature in the Sandbox environment:

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.