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.
This guide uses orders as an example.
The pubsubnotificationsettings
service lets 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.
Set 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 resource to get the actual order.
The diagram below summarizes the new workflow.
- The Cloud Pub/Sub system notifies your server that there is an order.
- Your server receives the message.
- Your server calls the Orders resource to get the order information.
- The Orders resource returns the order information.
- 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.
- You register the events for which you'd like to receive Cloud Pub/Sub notifications.
- The Content API's
pubsubnotificationsettings.update
receives the request and sends you back acloudTopicName
. - You create a subscription for the topic and register the URL push endpoint with Cloud Pub/Sub.
- Cloud Pub/Sub accepts your subscription and associates that
cloudTopicName
with your URL. When messages are published to thatcloudTopicName
(for example, your order notifications), they will be sent to your URL push endpoint.
Register 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://shoppingcontent.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"
]
}
Subscribe 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
.
Receive 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.
Get Cloud Pub/Sub notification settings
For more information see
pubsubnotificationsettings.get
.
GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/pubsubnotificationsettings
{
"kind": "content#pubsubNotificationSettings",
"cloudTopicName": "projects/681163075750/topics/id_51579e90-b60c-48fb-87e1-122a88f46eb3",
"registeredEvents": [
"orderPendingShipment"
]
}