Terminal
Terminal/Skill
Guide to setting up Google Play real time developer notifications through Cloud Pub/Sub and processing subscription events safely.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill rtdnRTDN pushes subscription and purchase state changes from Google Play to your backend within seconds. Use it as the primary signal for entitlement updates; polling the Play Developer API on a schedule is a fallback, not a substitute.
Pin down the following before you write code:
DeveloperNotification JSON object with packageName, eventTimeMillis, and exactly one of subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, or testNotification. It carries a purchaseToken and a type code, not the full purchase state.purchases.subscriptionsv2.get or purchases.products.get and update entitlements from the API response, not the notification type.Decide push vs pull:
| Strategy | Pick when |
|---|---|
| Push subscription | You have a public HTTPS endpoint and want a webhook style integration with retries handled by Pub/Sub |
| Pull subscription | Your backend has no public URL, needs batch processing, or wants fine grained control over consumption rate |
Push is the simpler default. You can swap strategies later without changing the Play Console configuration.
Write the plan before provisioning anything.
play-billing-notifications). One topic handles subscriptions, one time products, and voided purchases.ack-deadline (60s is a reasonable starting point).roles/pubsub.publisher to google-play-developer-notifications@system.gserviceaccount.com on the topic.projects/YOUR_PROJECT_ID/topics/play-billing-notifications.Your webhook must return 2xx within the ack deadline to acknowledge the message. Any other response or a timeout causes Pub/Sub to retry with exponential backoff. Plan accordingly:
5xx response forces Pub/Sub to resend, which you want for transient failures. A 4xx response signals a permanent error and may drop the message (or send it to a dead letter topic if configured). Pick the status code deliberately.Because duplicates and out of order deliveries are guaranteed, every handler must be idempotent.
messageId. Persist processed message IDs with a TTL of 24 to 48 hours. Skip any replay you have already seen, then ack.eventTimeMillis per purchaseToken. Record the highest event time you have seen so you can detect stale events if you need to branch logic, but still call the API on every notification.purchaseToken rather than inserts. Revoking access must be safe to run twice; so must extending expiry.SUBSCRIPTION_ON_HOLD).gcloud pubsub topics create play-billing-notifications
gcloud pubsub topics add-iam-policy-binding \
play-billing-notifications \
--member=serviceAccount:google-play-developer-notifications@system.gserviceaccount.com \
--role=roles/pubsub.publisher
Missing this binding is the most common reason a freshly configured RTDN pipeline delivers no messages.
gcloud pubsub subscriptions create play-billing-sub \
--topic=play-billing-notifications \
--push-endpoint=https://api.yourapp.com/billing/rtdn \
--ack-deadline=60
For pull, omit --push-endpoint and run a subscriber loop in your backend.
In the Play Console, open Monetization setup, find Real time developer notifications, enter projects/YOUR_PROJECT_ID/topics/play-billing-notifications, click Send test notification, and save. A push subscriber should receive the test within seconds.
The push body wraps the notification in a Pub/Sub envelope. The data field is a base64 encoded JSON string.
{
"message": {
"data": "eyJ2ZXJzaW9uIjoiMS4wIiwi...",
"messageId": "136969346945",
"attributes": {}
},
"subscription": "projects/myproject/subscriptions/play-billing-sub"
}
Decode the payload:
import java.util.Base64
fun decodePubSubData(base64: String): String {
val bytes = Base64.getDecoder().decode(base64)
return String(bytes, Charsets.UTF_8)
}
Parse into a DeveloperNotification:
data class DeveloperNotification(
val version: String,
val packageName: String,
val eventTimeMillis: Long,
val subscriptionNotification: SubscriptionNotification? = null,
val oneTimeProductNotification: OneTimeProductNotification? = null,
val voidedPurchaseNotification: VoidedPurchaseNotification? = null,
val testNotification: TestNotification? = null
)
Route by which sub object is present, then by type code.
fun route(n: DeveloperNotification) {
when {
n.subscriptionNotification != null ->
handleSubscription(n.subscriptionNotification)
n.oneTimeProductNotification != null ->
handleOneTime(n.oneTimeProductNotification)
n.voidedPurchaseNotification != null ->
handleVoided(n.voidedPurchaseNotification)
n.testNotification != null ->
log("RTDN test received")
}
}
suspend fun onPubSubMessage(
messageId: String,
n: DeveloperNotification
) {
if (store.hasProcessed(messageId)) return
route(n)
store.markProcessed(messageId)
}
suspend fun handleSubscription(s: SubscriptionNotification) {
metrics.increment("rtdn.sub.${s.notificationType}")
val sub = playApi.getSubscriptionV2(
packageName, s.purchaseToken
)
updateEntitlementFromApiState(s.purchaseToken, sub)
}
Apply the same pattern to one time products (purchases.products.get) and voided purchases (revoke the entitlement keyed on the purchase token).
Chapter 10 of the handbook documents the 14 subscription types, 2 one time product types, voided purchase, and test notification. The full catalog of 22 subscription notification types (including newer types such as pending plan changes and winback acceptances) is maintained in Appendix A of the handbook. See the RTDN chapter on revenuecat.com for in depth coverage of each type; see the rtdn-reference skill or the appendix linked from it for the complete list.
Key subscription types you must handle correctly:
| Type | Code | Action |
|---|---|---|
| SUBSCRIPTION_RECOVERED | 1 | Restore access; payment recovered from hold |
| SUBSCRIPTION_RENEWED | 2 | Extend expiry to new expiryTimeMillis |
| SUBSCRIPTION_CANCELED | 3 | Keep access until expiryTimeMillis; do not revoke now |
| SUBSCRIPTION_PURCHASED | 4 | Server side safety net; verify the purchase |
| SUBSCRIPTION_ON_HOLD | 5 | Revoke access; keep the subscription record |
| SUBSCRIPTION_IN_GRACE_PERIOD | 6 | Keep access; surface a payment update prompt |
| SUBSCRIPTION_RESTARTED | 7 | User resubscribed before expiry; confirm auto renewing |
| SUBSCRIPTION_PRICE_CHANGE_CONFIRMED | 8 | Record new price for next renewal |
| SUBSCRIPTION_DEFERRED | 9 | Fetch new expiry time and extend access |
| SUBSCRIPTION_PAUSED | 10 | Revoke access until resume |
| SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED | 11 | Sync pause schedule with API state |
| SUBSCRIPTION_REVOKED | 12 | Revoke access immediately |
| SUBSCRIPTION_EXPIRED | 13 | Terminal; revoke if not already |
| SUBSCRIPTION_PENDING_PURCHASE_CANCELED | 14 | Clean up pending record; no revocation needed |
One time products: ONE_TIME_PRODUCT_PURCHASED (1) and ONE_TIME_PRODUCT_CANCELED (2). Voided purchases: always revoke and record for reconciliation; productType marks subscription (1) vs one time (2) and refundType marks full (1) vs quantity based (2).
testNotification payload.SUBSCRIPTION_PURCHASED then SUBSCRIPTION_CANCELED with matching purchase tokens.messageId twice and confirm your handler runs the business logic exactly once.500 from the webhook and confirm Pub/Sub retries and eventually delivers after you return to 200.