Webhook Reference

RevenueCat Webhooks

URL: https://{slug}.billing.aldero.io/webhooks/revenuecat Auth: Authorization header with tenant-specific secret (configured in dashboard Settings > Billing > Webhooks)

Events Handled

Event Type	Result	Status
`INITIAL_PURCHASE`	Creates entitlement	`active`
`NON_RENEWING_PURCHASE`	Creates entitlement (consumable)	`active`
`RENEWAL`	Creates/updates entitlement	`active`
`PRODUCT_CHANGE`	Creates entitlement for new product	`active`
`CANCELLATION`	Updates entitlement (stays active until period end)	`active`
`UNCANCELLATION`	Updates entitlement	`active`
`EXPIRATION`	Updates entitlement	`expired`
`BILLING_ISSUE`	Updates entitlement	`expired`
`SUBSCRIPTION_PAUSED`	Updates entitlement	`paused`
`SUBSCRIPTION_EXTENDED`	Updates entitlement	`active`
`SUBSCRIBER_ALIAS`	Skipped (no subscription data)	—
`TRANSFER`	Skipped (handled by RevenueCat SDK login)	—

Tenant Resolution

The tenant is resolved from the webhook URL subdomain. Set the webhook URL per tenant in RevenueCat:

https://faxdash.billing.aldero.io/webhooks/revenuecat
https://myotherapp.billing.aldero.io/webhooks/revenuecat

Environment Detection

RevenueCat sends environment: "PRODUCTION" or "SANDBOX" in the event payload. The billing service tags entitlements accordingly.

Product Resolution

The billing service looks up the product by product_id (or new_product_id for PRODUCT_CHANGE) in the tenant’s product catalog. Products are matched by providerProductId field.

If the product isn’t found, the entitlement is still created with the raw product ID — but without features or grants.

Stripe Webhooks

URL: https://{slug}.billing.aldero.io/webhooks/stripe Auth: Stripe-Signature header verified against tenant-specific webhook secret

Events Handled

Event Type	Action
`customer.subscription.created`	Creates entitlement
`customer.subscription.updated`	Updates entitlement status
`customer.subscription.deleted`	Updates entitlement to expired
`invoice.paid`	Refreshes subscription entitlement
`invoice.payment_failed`	Handled by subscription.updated

Tenant Resolution

Same as RevenueCat — from the webhook URL subdomain.

User Resolution

Stripe subscriptions must include metadata.userId set at checkout time. Without it, the webhook is skipped.

Environment Detection

Uses subscription.livemode — true for production, false for sandbox.

Webhook Recovery

If webhooks are missed or fail, use the Sync feature:

Dashboard

Go to Billing > Subscribers, find the user, click Sync.

API

curl -X POST https://faxdash.billing.aldero.io/v1/sync/{userId} \
  -H "Authorization: Bearer bil_..."

This fetches the user’s full purchase/subscription history from RevenueCat and reconciles all entitlements.

Webhook Secret Configuration

Per-tenant webhook secrets are managed in the dashboard:

Go to Settings > Billing > Webhooks
Enter the RevenueCat Authorization secret and/or Stripe webhook signing secret
Save

The secrets are stored per-tenant and verified on each incoming webhook.

SMS Multi-Factor Auth