Working with Platform Notifications

After notification delivery is enabled for your application, eBay will send notifications related to listings that your application has submitted by the AddItem, AddItemWithProduct, RelistItem, or RelistItemWithProduct and ReviseItem functions. When your application calls one of these functions, eBay identifies the application by its AppId. 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.

SOAP Message Fields

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

An HTTP header.
An XML processing instruction (the Platform Notifications feature only supports UTF-8 character encoding).
A SOAP envelope containing a SOAP header and SOAP body

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:

Post -- contains the path of the URL that you provide.
PROTOCOL -- HTTP/1.1 (The HTTP post is sent via HTTP, not HTTPS, because the data does not need the security of a certificate.)
HOST -- contains the server specified in the URL that you provide
CONTENT_TYPE -- contains "text/xml" and the XML encoding of the message
CONTENT_LENGTH -- contains the length, in the form of a number, of the SOAP message
SOAPACTION -- contains a URL that ends with the name of the event that the notification is being sent for. The value at the end will be one of the values specified in the NotificationEventTypeCodeType type in the schema.

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

Example 40-1 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:

Compute the MD5 hash using a standard routine, such as Microsoft crypto API, or OpenSSL open source.

You can find more information about these routines at:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnw98bk/html/98gettingstarted.asp

and

http://www.openssl.org/

Convert the hash to Base64 encoding.
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:

Example 40-2 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

Notification Payloads

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

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

See the following table (Table 40-2) for a list of notifications and their corresponding API calls.

Table 40-2 API Call Payloads for Notifications 

Notification	API Call Payload
AskSellerQuestion	GetMemberMessages
AuctionCheckoutComplete	GetItemTransactions with default detail level
BestOffer	GetBestOffers
CheckoutBuyerRequestsTotal	GetItemTransactions with default detail level
EndOfAuction	GetItemTransactions with ReturnAll detail level
Feedback Notifications	GetFeedback with ReturnAll detail level
FixedPriceEndOfTransaction	GetItemTransactions with default detail level
FixedPriceTransaction	GetItemTransactions with ReturnAll detail level
INR (ItemNotReceived) Notifications	GetDispute
ItemRevised	GetItem
ItemRevisedAddCharity	GetItem
MyMessages Notification	GetMyMessages with ReturnHeaders or ReturnMessages detail level
OutBid	GetItem with default detail level
SecondChanceOffer	GetItem with default detail level
ThirdPartyCartCheckout	GetCart
UPIBuyerResponseDispute	GetDispute
UPISellerClosedDispute	GetDispute
UPISellerOpenedDispute	GetDispute
UPISellerRespondedToDispute	GetDispute

Responding to a Notification

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 URL or your application' ability to respond), eBay may stop sending notifications for events associated with your application's AppId.

Receiving Notifications by Email

With version 387, you can specify that you want to receive notifications by email, rather than posted to a server. To do this, use SetNotificationPreferences.

Pass an ApplicationDeliveryPreferencesType to SetNotificationPreferences. In the ApplicationDeliveryPreferencesType, set ApplicationURL to a URL that starts with mailto:// or mailto: followed by a valid email address, for example:

mailto://someone@xyz.com

mailto:anyone@acme.com

In ApplicationDeliveryPreferencesType, also set ApplicationEnable to Enable to indicate that you want to turn on notifications sent to the email URL.

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:

Subscribe to the notifications you want (see Subscribing to Platform Notifications).
Activate the platform notifications you want to test (see Activating Platform Notifications).
Create listings, bids, disputes, or anything else you want to test, using the Sandbox web interface (at http://sandbox.ebay.com). Do something that generates a notification that your application is subscribed to, such as leaving feedback for a seller or having a buyer respond to a dispute.
Make sure that your application can receive notifications.
Make sure that your application responds to notifications with an HTTP status of 200 OK.
Use GetNotificationsUsage to review the platform notification usage history for your application.
Contact eBay Developer Technical Support if you have questions.

User-Contributed Notes