Push Subscriber Guide

Pub/Sub supports both push and pull message delivery. For an overview and comparison of pull and push subscriptions, see, see the Subscriber Overview. This document describes push delivery. For a discussion of pull delivery, see the Pull Subscriber Guide.

Receiving Push Messages

The Pub/Sub server sends any messages for your subscription to the webhook address you have configured. Your webhook application needs to handle incoming messages and return an HTTP status code to indicate success. Any of the following HTTP status codes is interpreted as success by the Pub/Sub system: 200, 201, 204, or 102. If your service returns any other code, Google Cloud Pub/Sub retries delivering the message for up to the maximum retention time set for the subscription.

To regulate the rate of push message delivery, Google Cloud Pub/Sub uses a slow-start algorithm. With slow-start, Google Cloud Pub/Sub starts by sending a single message at a time, and doubles up with each successful delivery, until it reaches the maximum number of concurrent messages outstanding. Any time there is a delivery failure, the number of messages outstanding allowed for the subscription is halved.

The specifics of coding your handler are dependent on your environment. Here is a protocol example for receiving push messages:

Request:

POST https://www.example.com/my-push-endpoint
{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
    "message_id": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Response:

204 No Content

A response with 204 status code is considered as an implicit acknowledgement.

For examples of how to accomplish this in App Engine Flexible environments, see Writing and Responding to Pub/Sub Messages for Python, Node.js, Go, Ruby, PHP and Java.

Stopping and Resuming Delivery

To suspend receiving messages for a subscription, set the push endpoint URL to an empty string, effectively converting the subscription to a pull one. The messages will accumulate, but will not be delivered. To resume receiving messages, set the URL to a valid endpoint again. You can do this with the subscription update method of the gcloud command-line tool, for example.

To permanently stop delivery, delete the subscription.

Message Acknowledgment Deadline

You can configure a default acknowledgment deadline for push subscriptions. However, unlike for pull subscriptions, the deadline cannot be extended for individual messages. The deadline is effectively the amount of time the endpoint has to respond to the push request.

Configuring HTTP Endpoints

You need a publicly accessible HTTPS server to handle POST requests in order to receive push messages. The server must present a valid SSL certificate signed by a certificate authority and routable by DNS. You also need to validate that you own the domain (or have equivalent access to the endpoint). Finally, you must register the endpoint domain with the GCP project. Note that these steps are considerably simplified on App Engine, where SSL certificates are provided and verification requirements can be relaxed.

App Engine Standard Endpoints

The easiest way to get started with push endpoints is with an App Engine app hosted on the appspot.com domain. If the app is in the same GCP project as the subscription, there are no domain verification requirements. Otherwise, you must verify and register your domain (see below). We recommend keeping the subscriber and the push endpoint in the same project whenever possible. For example, if you are a publisher who wants to fan out to multiple subscribers in different projects, you should create the subscriptions in the same projects as the push endpoints.

Here are some additional tips for working with App Engine endpoints:

  • Use the prefix /_ah/push-handlers/ for the push endpoint URL path

    For example: myapp.appspot.com/_ah/push-handlers/myhandler. This allows the endpoint to receive push messages from Google Cloud Pub/Sub, which is accomplished by the /_ah/push-handlers/ prefix.

    You are not required to use the /_ah/push-handlers/ prefix. But if you use any other prefix, you'll need to configure it to allow unauthenticated (not logged in) requests, and to be reachable by using a tool such as cURL.

  • Protect the /_ah/push-handlers/.* URLs by requiring administrator login.

    This prevents unauthorized access to the URL endpoint. To do this you need to add the login: admin option in your app.yaml as in this python example, or a <security-constraint> as in this Java example.

Registering endpoints

The following steps are required for non-App Engine endpoints, as well as for App Engine endpoints that are not registered in the same Cloud project as the subscriber. To prevent unwelcome push message traffic, you must establish some ownership of the domain. First, you must prove that you have administrative access to the domain. Second, you must allow the GCP project to generate traffic to that domain.

Step 1: Verify you have access to the domain

Complete the site verification process using Search Console. Be sure to register the https:// version of your site URL. For more details, see the site verification help documentation.

Step 2: Register your domain in API manager

In addition to proving you have access to the domain (or endpoint URL) as a user, you must also allow the GCP project containing the subscription access to that domain. This step will not work until you complete Step 1. Once you've verified your access to the domain, register it with your project:

  1. Go to the Google Cloud Platform Console.
  2. Select your project.
  3. Open the navigation sidebar in the top left corner, select API Manager, then select Credentials.
  4. Select Domain verification.
  5. Select Add domain.
  6. Fill in the form, then again select Add domain.

At this point, the Google Cloud Platform Console checks your domain against the ones that you’ve verified in Search Console. Assuming that you’ve properly verified the domain, the page updates to show your new list of allowed domains.

You now can use any of these domains to receive push messages. To do so, you need to configure them as endpoints when you create a Google Cloud Pub/Sub subscription. See Configuring Subscriptions for details.

Send feedback about...

Cloud Pub/Sub