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/webhooks/apple/app_YOUR_APP_ID

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. A webhook failure never affects RTDN/ASSN processing itself — Tierux's internal store-notification handling always completes independently of your endpoint's availability.