Push Delivery

This document explains how the Pubsubnotificationsettings service works and how it can be set up to allow you to be notified of various events. For an explanation of the underlying technology, refer to What Is Cloud Pub/Sub? and Subscriber overview.

We're going to focus on orders in this document because that's a common, concrete example and the only one currently implemented.

Up until now, you have had to call the service every few minutes to get your orders. This is called "pull" because you call Google to pull your orders.

The Pubsubnotificationsettings service allows you to receive notifications that an order has been created. This is called "push" since Google will push notifications to you about events, such as orders, that happen on the Google side.

For orderPendingShipment, the system sends a notification for every order that gets into the pendingShipment state. If the notification isn't acknowledged, it is re-sent according to the settings in Cloud Pub/Sub.

Setting up notifications

To receive notifications, you need a server that can receive HTTP calls. Notifications are delivered to your server as HTTP POST requests from Google. Your web server is configured to receive the order ID from a Google service, and then you call the Orders API to get the actual order.

The diagram below summarizes the new workflow.

  1. The Cloud Pub/Sub system notifies your server that there is an order.
  2. Your server receives the message.
  3. Your server calls the Orders API to get the order information.
  4. The Orders API returns the order information.
  5. Your order management system processes the order and acknowledges back to Cloud Pub/Sub.

To set up push notifications, call the Pubsubnotificationsettings.update method (passing in the registeredEvents you want to be notified by) to get a cloudTopicName.

In the case of orderPendingShipment, this means that when your orders get to the pendingShipment state, a message with the event details is then published to the Cloud Pub/Sub topic.

Next, subscribe to the cloudTopicName and register your URL as the push endpoint.

From then on, Cloud Pub/Sub will send notifications to your URL whenever there is an order.

At the time of this writing, orderPendingShipment—orders in pendingShipment state—is the only message type that is available but others are planned.

The diagram below shows the steps in this process.

  1. You register the events for which you'd like to receive Cloud Pub/Sub notifications.
  2. The Content API's Pubsubnotificationsettings.update receives the request and sends you back a cloudTopicName.
  3. You create a subscription for the topic and register the URL push endpoint with Cloud Pub/Sub.
  4. Cloud Pub/Sub accepts your subscription and associates that cloudTopicName with your URL. When messages are published to that cloudTopicName (for example, your order notifications), they will be sent to your URL push endpoint.

Registering for events

To get the complete list of supported registeredEvents, refer to the documentation for Pubsubnotificationsettings. The documentation uses orderPendingShipment as an example, which results in notifications being sent to you when an order is received and reaches the pendingShipment state.

Request

For more details, refer to Pubsubnotificationsettings.update.

PUT https://www.googleapis.com/content/v2.1/merchantId/pubsubnotificationsettings
{
   "registeredEvents":[
      "orderPendingShipment"
   ]
}

Response

{
 "kind": "content#pubsubNotificationSettings",
 "cloudTopicName": "projects/681163075750/topics/id_51579e90-b60c-48fb-87e1-122a88f46eb3",
 "registeredEvents": [
  "orderPendingShipment"
 ]
}

Subscribing to Cloud Pub/Sub

To subscribe to Cloud Pub/Sub, use the topic name (cloudTopicName) that you got from the call to Pubsubnotificationsettings.update and your server URL. Also, use the same credentials as those for the Content API. For more details, visit Managing topics and subscriptions.

After you've successfully subscribed, you should start receiving notifications from the system. To test your system, we recommend that you create a test order using Orders.createtestorder.

Receiving push messages

For more information about setting up push subscriptions, refer to Using push subscriptions.

The message uses the HTTP POST method.

POST https://www.example.com/my-push-endpoint

A Cloud Pub/Sub push request looks like this example below. Note that the message.data field is base64-encoded.

{
   "message":{
      "data":"eyAKICAgIm1lcmN...AgIH0KfQo=",
      "messageId":"136969346945"
   },
   "subscription":"projects/myproject/subscriptions/mysubscription"
}

This is the format of the decoded data field in the above message.

{
   "merchantId":"123456789",
   "resource":{
      "resourceType":"ORDER",
      "resourceId":"TEST-1234-56-7890"
   },
   "event":{
      "eventType":"ORDER_PENDING_SHIPMENT"
   }
}

In this message, the resourceType tells you the type of the message. The resourceId contains the order number. The eventType is the type you used when calling the service; currently orderPendingShipment is the only available eventType.

Field Description
MerchantId Your merchant ID.
resourceType Type of message.
resourceId Order number.
eventType Type of event.

Your push endpoint needs to handle incoming messages and return an HTTP status code to indicate success or failure. A success response is equivalent to acknowledging a message. The status codes interpreted as message acknowledgements by the Cloud Pub/Sub system are 200, 201, 202, 204, and 102; for example, 204 No Content.

For push subscriptions, Cloud Pub/Sub does not send a negative acknowledgment. If your webhook does not return a success code, Cloud Pub/Sub retries delivery until the message expires after the subscription's message retention period. The deadline is effectively the amount of time the endpoint has to respond to the push request.

Getting Cloud Pub/Sub notification settings

For more information see Pubsubnotificationsettings.get.

GET https://www.googleapis.com/content/v2.1/merchantId/pubsubnotificationsettings
{
  "kind": "content#pubsubNotificationSettings",
  "cloudTopicName": "projects/681163075750/topics/id_51579e90-b60c-48fb-87e1-122a88f46eb3",
  "registeredEvents": [
    "orderPendingShipment"
  ]
}