Configure Your Webhook URL

After adding your app to RefundShield, a unique webhook URL is generated for it. You need to configure Google Cloud Pub/Sub and enable Real-time Developer Notifications (RTDN) so Google Play forwards refund events to RefundShield.

Step 1: Find Your Webhook URL

1. In RefundShield, open your app's detail page
2. Copy the Webhook URL displayed under the app name, it looks like:
   https://refundshield.io/webhook/google/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Each app has its own unique webhook URL. Make sure you use the correct one when configuring multiple apps.

Step 2: Create a Pub/Sub Topic

1. Sign in to Google Cloud Console
2. Open the navigation menu (☰) in the top left, scroll down to Pub/Sub and go to Topics. If Pub/Sub is not visible in the sidebar, use the search bar at the top and type "Pub/Sub".
3. Click Create Topic
4. Give it a name (e.g., refundshield-rtdn) and click Create
5. Copy your Topic name ( it looks like projects/your-project-id/topics/refundshield-rtdn ), you will need it in step 5

Step 3: Grant Publish Permission to Google Play

Google Play Console publishes notifications to your topic using its own system account. You must grant it publish access:

1. On right of the topic page, go to the Permissions tab
2. Click Grant Access
3. In Add principals, enter:
   [email protected]
4. Select the role Pub/Sub Publisher
5. Click Save

Important: without this step, Google Play cannot deliver notifications and the test will fail.

Step 4: Create a Push Subscription

1. On the topic page, click Create Subscription
2. Give it a name (e.g., refundshield-push)
3. Set Delivery type to Push
4. Paste your RefundShield webhook URL in the Endpoint URL field
5. Under Authentication, enable it and select your Service Account (e.g., [email protected])
6. Click Create

Step 5: Enable RTDN in Google Play Console

1. Go to Google Play Console
2. Select your app
3. Go to Monetise with Play → Monetisation setup
4. Under Google Play Billing check Enable real-time notifications
5. Enter your Pub/Sub topic name in the format projects/{project_id}/topics/{topic_name}, you can find the full topic name in Google Cloud Console under Pub/Sub → Topics
6. Click Save

Verify It Works

Google Play Console lets you send a test notification to confirm your setup immediately, no need to wait for a real refund.

1. In Google Play Console, go to your app → Monetization → Billing settings
2. Under Real-time Developer Notifications, click Send test notification

If everything is configured correctly, RefundShield receives the notification and the webhook setup banner disappears from your app's overview page. No test data is shown in your dashboard or events, it's a silent verification.

Once verified, refund events will appear in your app's Events tab as they happen.

Forward Notifications to Another Endpoint (Optional)

A Pub/Sub push subscription can only deliver to one endpoint. If you also need the exact same notifications on your own server, you can set up webhook forwarding from the app's edit page:

1. Open your app in RefundShield and go to Edit
2. In the Webhook forwarding section, enter your endpoint URL (HTTPS only)
3. Save the app

Every notification RefundShield receives is then forwarded unchanged, including the original Pub/Sub envelope and the Authorization JWT, shortly after it has been processed.

Note about JWT verification: the original Google JWT has RefundShield's webhook URL as its audience, not your endpoint. If your server verifies the JWT with a standard library, you will need to accept RefundShield's URL as the audience (or skip the audience check). The signed body remains verifiable with Google's public keys.