Push Subscriber Guide

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

Receiving Push Messages

The Cloud 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 Cloud Pub/Sub system: 200, 201, 202, 204, or 102. If your service returns any other code, Cloud Pub/Sub retries delivery for 7 days (the standard message retention period). At that point, the message is deleted.

Note that push subscriptions are subject to a set of quotas and resource limits.

An outstanding message is a message that has been delivered to the push endpoint but has not yet been acknowledged.

In order to determine the optimal delivery rate for your system (while minimizing the possibility of overwhelming it at first), Cloud Pub/Sub uses a slow-start algorithm.

  • The system starts by sending a single message at a time.
  • With each successful delivery, the number of messages that are sent concurrently is doubled.
  • The rate at which the system delivers concurrent messages continues to double until there is a delivery failure or the system reaches a quota or resource limit.
  • For each delivery failure, the number of concurrent requests to the endpoint will halve, until a minimum of one request at a time is reached.

Note that this algorithm assumes that there are enough published messages in the queue to sustain this throughput. Ultimately, the pushing rate is tightly related to the publishing rate.

The specifics of coding your handler are dependent on your environment. Below is a protocol example for receiving push messages. Note that the message.data field is base64-encoded.

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 Cloud Pub/Sub Messages for Python, Node.js, Go, Ruby, PHP and Java.

Stopping and Resuming Delivery

To stop Cloud Pub/Subfrom sending requests to the push endpoint, change the subscription to a pull type. Messages will accumulate, but will not be delivered. Note that it may take several minutes for this changeover to take effect.

To resume push delivery, set the URL to a valid endpoint again. 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

In order to receive push messages, you need a publicly accessible HTTPS server to handle POST requests. 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.

You can also secure messages using a secret token. See Writing and Responding to Cloud Pub/Sub Messages for App Engine examples.

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 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 APIs & services

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 APIs & services, 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 Cloud Pub/Sub subscription. See Configuring Subscriptions for details.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Pub/Sub