Webhooks

What webhooks does Tierux handle?

Tierux processes two types of store-originating notifications automatically:

• Google Play RTDN — Real-Time Developer Notifications via Cloud Pub/Sub for subscription lifecycle events (renewal, cancellation, hold, grace, expiry, revocation).
• Apple App Store Server Notifications v2 — JWS-signed notifications for subscription events (renewal, expiry, billing retry, refund, etc.).

Both are processed server-side. Your backend doesn't need to listen for webhooks — just read entitlement state from the REST API.

Google Play RTDN setup

Tierux operates a single shared Pub/Sub topic with an authenticated push subscription into its backend — there is no Pub/Sub infrastructure, IAM, or environment configuration on your side. Your only step is pointing your app's Play Console at the shared topic:

# Play Console → your app → Monetize → Monetization setup
Cloud Pub/Sub topic: "projects/simple-pay-wall/topics/play-rtdn"

Notifications carry your app's package name, which is how Tierux routes them to the right app. See the RTDN guide for the full flow and test-notification steps.

Apple Server Notifications setup

Apple App Store Server Notifications v2 are configured in App Store Connect. Enter your app's Server URL under App Store → General → App Store Server Notifications. The URL follows the pattern:

https://tierux.com/api/v1/apple/assn/YOUR_APP_ID

Replace YOUR_APP_ID with your app's ID from the Tierux dashboard (it starts with app_). Use the same URL for both the Production and Sandbox Server URL fields.

Tierux automatically validates the JWS signature of incoming Apple notifications, decodes the payload, and updates entitlement state.

Notification types processed

// Google Play RTDN events
SUBSCRIPTION_PURCHASED, RENEWED, CANCELED,
ON_HOLD, IN_GRACE_PERIOD, RESTARTED,
EXPIRED, REVOKED, PAUSED, PAUSE_SCHEDULE_CHANGED,
DEFERRED, PRICE_CHANGE_CONFIRMED

// Apple App Store notification types
SUBSCRIBED, DID_RENEW, DID_FAIL_TO_RENEW,
EXPIRED, DID_CHANGE_RENEWAL_STATUS,
REFUND, PRICE_INCREASE_CONSENT, REVOKE

All notifications update the user's entitlement state automatically. Your backend queries the latest state via GET /api/v1/entitlements/{userId}/{entitlement}.

Webhook reliability

Tierux processes webhooks synchronously on receipt. For Google Play RTDN, Pub/Sub provides at-least-once delivery — Tierux's deduplication (the Pub/Sub message ID is stored on the entitlement and repeat deliveries are skipped) ensures idempotent processing. For Apple, JWS-based server notifications include a unique notification UUID for dedup.

Outbound developer webhooks (v1)

Beyond processing store notifications internally, Tierux can forward the same subscription-lifecycle events to your own backend as a signed HTTP POST — so you don't have to poll the entitlement API to react to renewals, cancellations, or refunds.

Configure one webhook URL per app via the MCP set_webhook tool (preview + confirm, like every other write in Tierux). On confirm, a fresh signing secret is generated and returned exactly once — store it immediately, it is never shown again (only an encrypted copy is kept server-side).

// Event types dispatched to your webhook
renewal, billing_retry, grace_period,
cancellation_pending, expired, refund

Each delivery is a POST with this contract:

// Headers
Content-Type: application/json
X-Tierux-Event: renewal          // one of the event types above
X-Tierux-Delivery: 3f2a1c9e-...   // unique per delivery attempt
X-Tierux-Signature: sha256=<hex>  // HMAC-SHA256 over the raw body

// Body — the raw UserEvent JSON, e.g.
{
  "id": "evt_abc123",
  "appId": "app_123",
  "userId": "user_1",
  "type": "renewal",
  "productId": "felper_pro_monthly",
  "via": "main",
  "createdAt": "2026-07-03T00:00:00.000Z"
}

Verify the signature on your end before trusting the payload:

// Node.js — verify X-Tierux-Signature against the raw request body
const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

v1 delivery contract: at-most-once. There is no retry queue and no dead-letter queue — if your endpoint is down, times out (5s), or returns a non-2xx status, that delivery is dropped and never redelivered. This is a deliberate v1 simplification; a delivery dashboard and retries are on the roadmap. Redirects are not followed: configure the exact URL that answers the POST, because a 3xx response (for example an apex-to-www or trailing-slash redirect) drops the event. A webhook failure never affects RTDN/ASSN processing itself — Tierux's internal store-notification handling always completes independently of your endpoint's availability.