Webhooks

Qonversion validates user receipts with app stores and sends subscription events to your HTTP endpoints. Keep in mind events delivery time when using webhooks to manage subscriber statuses on your back-end. Most events reach your endpoint within seconds, usually within a minute. The exact latency depends on store-side notification timing, your server’s response time, and any retries. For real-time subscription status on the client-side, use the checkEntitlements method of the Qonversion SDK.

1. Set up the webhook URL

Navigate to the Integrations section in your Qonversion account and select Webhooks. Enter an Integration Name, choose the platform, and click Continue.
Register your URL and Qonversion will send a request
Settings save automatically as you enter them. If the endpoint server returns a 200 response code, the integration is activated.

Sandbox webhook URL

The Webhooks integration form also exposes a separate Sandbox Webhook URL field. Production-environment events are delivered to the main URL; sandbox-environment events (environment: "sandbox") are delivered to the Sandbox URL when it is set. If you receive sandbox events but leave the Sandbox URL empty, Qonversion does not deliver them, and they are not retried.

2. Request format

Qonversion sends POST request to webhook URL every time an event occurs. The request includes an Authorization header of the form Basic <token>, where <token> is the Header Authorization-Token Value you configured in the Webhooks integration settings - it is sent as-is, not base64-encoded as in standard HTTP Basic auth. Use it to protect your server from unwanted requests.

SSL certificate

Remember, maintaining secure connections is essential for the integrity and reliability of your application’s communication.Ensure the SSL certificate used is not expired and your server’s CA bundle is up-to-date to recognize the latest root CAs.

Request Header:

Authorization: Basic {Header Authorization-Token}
Accept: application/json

Request Body:

{
    "id": "6a656d86-3f1c-59c8-8469-53df065ef02c",
    "event_name": "trial_converted",
    "user_id": "3YjIDEUDaf_5g4IdWw6zcMlLgfg_YQp2",
    "custom_user_id": "",
    "identity_id": "",
    "advertiser_id": "9FD1767D-8B48-45BD-A2F4-1C08B08E56F2",
    "time": 1600000000,
    "created_at": 1600000000,
    "product_id": "com.myapp.subs.9.99.trial",
    "period_type": "regular",
    "revenue": {
        "value": 7.99,
        "value_usd": 9.99,
        "currency": "GBP",
        "is_proceed": 0,
        "proceeds_rate": 70
    },
    "price": {
        "value": 7.99,
        "value_usd": 9.99,
        "currency": "GBP"
    },
    "transaction": {
        "transaction_id": "500000601234560",
        "original_transaction_id": "500000601234560",
        "expires": 1600259200,
        "grace_period_expires": null,
      "transaction_date": 1600004000,
			"promo_offer_id": "appname.subscription.month.withoutTrial.promo"

    },
    "properties": {
        "_q_email": "me@qonversion.io"
    },
    "device_id": "0E66565D-4F3A-E366-B3D4-B5DDAC6BBE2E",
    "app_version": "2.1.4",
    "sdk_version": "3.1.0",
    "environment": "production",
    "platform": "iOS",
    "ip": "10.0.0.1",
    "country": "GB",
    "storefront": "GBR",
    "old_product_id": "com.myapp.subs.4.99.trial",
    "new_product_id": "com.myapp.subs.9.99.trial",
    "locale": "en_US",
    "subscription_group": "784563",
    "user_install_date": 1600000000,
    "project_name": "Sample App",
    "app_id": "com.sample.app",
    "quantity": 3,
    "subscription_renew_count": 5,
    "billing_plan_type": "monthly",
    "commitment": {
        "installment_number": 3,
        "total_installments": 12,
        "expires_at": 1790000000,
        "total_price": 119.88
    },
    "entitlements": [
        {
            "active": true,
            "expires": 1654215637,
            "id": "plus",
            "product": {
                "product_id": "main",
                "subscription": {
                    "current_period_type": "regular",
                    "renew_state": "will-renew"
                }
            },
            "source": "stripe",
            "started": 1652438020
        }
    ],
    "asa_attribution": {
        "org_id": 1234567890,
        "campaign_id": 1234567890,
        "adgroup_id": 1234567890,
        "keyword_id": 1234567890,
        "ad_id": 1234567890,
        "country_or_region": "DE",
        "conversion_type": "Download",
        "click_date": "2024-08-21T16:10Z",
        "impression_date": "2024-08-21T16:10Z",
        "claim_type": "Impression",
        "supply_placement": "APPSTORE_SEARCH_RESULTS"
    }
}

billing_plan_type and commitment are present only for Apple 12-month-commitment subscriptions, available on iOS 26.4 and later. Such a subscription’s period stays yearly while it is billed in twelve monthly installments, so revenue and price on this event hold the monthly installment, not the yearly amount. The monthly amounts alone give no hint that the subscription is yearly — billing_plan_type and commitment are the only way to tell an installment apart from an ordinary monthly subscription. Commitment plans billed other than in monthly installments are not currently reported.

Column	Required	Description
id	yes	Unique identifier of the event within one Webhooks integration, formatted as a UUID (version 5). Every retry and every resend of that delivery repeats it, so use it as the idempotency key when deduplicating on your side. If you have configured more than one Webhooks integration for the same app, each of them receives its own copy of the event carrying the same `id` — deduplicate per integration endpoint rather than globally.
event_name	yes	Event name provided in the integration config. It defaults to the canonical event name, but you can rename it per integration in the Qonversion dashboard. See the details on the events tracked here
user_id	yes	Unique user identifier assigned by Qonversion
custom_user_id	yes	Unique user identifier that you can set with Qonversion SDK methods:User Identifiers
identity_id	yes	Unique user ID for the authenticated users that you can set using identify method of the Qonversion SDK
advertiser_id	yes	IDFA or AAID
time	yes	The time an app store changed a subscription status or a time Qonversion detected the change in the UNIX epoch time format in seconds. Read more about events timehere
created_at	yes	The time Qonversion generated the event
product_id	yes	App Store or Google Play Store product identifier
period_type	yes	The phase of this transaction: `trial` for a free trial, `intro` for an introductory offer period, `promotional` for an App Store promotional offer, offer code or win-back offer, and `regular` for a full-price charge. A transaction can satisfy several of these at once, so the value is resolved in a fixed order and the first match wins: `trial`, then `promotional`, then `intro`, then `regular`. An Apple free trial is also an introductory offer, so it reports `trial` rather than `intro`; a promotional offer with a free payment mode reports `trial` rather than `promotional`; and a promotional offer inside an introductory period reports `promotional` rather than `intro`. `regular` is also what an event that carries no transaction to classify receives. It describes the transaction the event reports, unlike `entitlements`, which describes the access the user holds right now — the two are computed independently, so treat them as separate fields rather than expecting them to agree. Store coverage differs: the App Store can report all four values; Google Play reports `trial`, `regular` and, for a minority of transactions, `intro`, but never `promotional`; Stripe and Paddle report only `trial` or `regular`.
revenue	yes	Dictionary with transaction revenue details. Only events with value filled
price	yes	Dictionary containing the price details of the product
transaction	yes	Dictionary with store transaction IDs and expiration timestamp
properties	yes	User properties provided by SDK as a JSON object (always present; sent as `{}` when the user has no properties). Read more about user properties here.
device_id	yes	identifierForVendor or Settings Secure Android ID.
app_version	no	Application version.
sdk_version	no	Qonversion SDK version.
environment	yes	”production” or “sandbox”.
platform	yes	”iOS”, “Android”, “Stripe”, or “Paddle”.
ip	yes	Application device IP address.
country	yes	A two-letter code representing a country, defined by theISO 3166-1 alpha-2standard, is determined on the Cloud provider’s side based on the IP address of the incoming request.
storefront	no	For Apple purchases, the App Store country or region as an ISO 3166-1 alpha-3 code, e.g. `CHN`, `USA`, or `GBR`. Identifies the App Store storefront rather than the user’s physical location. Present when the event carries a transaction, with `null` when the value is unavailable; omitted when there is no associated transaction. Configure an App Store Connect API Certificate to let Qonversion retrieve Apple storefront data. Always `null` for Stripe and Paddle.
old_product_id	no	Previous product (for product change events).
new_product_id	no	New product (for product change events).
locale	yes	A two-letter code representing a device language based on the device locale.
subscription_group	yes	`subscription_group_identifier` for iOS or Google `base_plan_id` for Android. Empty string for Stripe events.
user_install_date	yes	Timestamp when the user last installed the application.
project_name	yes	The project name of your app from the Qonversion dashboard.
app_id	yes	Store App Id. App Store ID for iOS or Android Package Name for Android.
quantity	no	Number of consumable in-app purchases. For non-consumable items or subscriptions, it will always return 1. Only present when the event has an associated transaction.
subscription_renew_count	no	Total number of times a user’s subscription has been renewed. Only present for events that carry a renewal counter (e.g. subscription renewals).
billing_plan_type	no	Billing plan of an Apple 12-month-commitment subscription. Always `monthly`: the commitment is charged in twelve monthly installments while the subscription period stays yearly. Present only for commitment subscriptions on iOS 26.4 and later.
commitment	no	Apple 12-month-commitment details: `installment_number` and `total_installments` give this charge’s position in the commitment (for example, 3 of 12); `expires_at` is the commitment end date as a Unix timestamp in seconds; `total_price` is the price of the whole commitment in major units of the currency reported by `price.currency` / `revenue.currency`. Individual keys are omitted when Apple does not provide their values.
entitlements	yes	A snapshot of the entitlements the user holds at the moment the event was built — the access the user has now, not a property of the transaction this event reports. Always present: a JSON array (`[{...}, {...}]`) when the user holds entitlements, and `{}` otherwise. `{}` means only that no entitlements were known when the event was built: it is what a project that has not configured products and entitlements always receives, and it is equally what ships when the entitlements lookup fails or times out, because that failure is not surfaced in the payload. The two cases cannot be told apart, so never read `{}` as proof that a user lost access. `product.product_id` is the Qonversion product identifier, not the store SKU carried in the top-level `product_id`. Treat the nested objects as conditional: `product` is omitted for an entitlement granted by hand with no product behind it, `subscription` is omitted for non-renewable products, and each of its keys is omitted when its value is unset. `subscription.current_period_type` is `regular`, `trial` or `intro`; `subscription.renew_state` is `will-renew`, `canceled`, `billing-issue` or `unknown`. Our public API models the same concepts but spells three of these values differently — `normal`, `will_renew` and `billing_issue` — and has no counterpart for `unknown` at all, so map the values rather than comparing the strings directly.
asa_attribution	no	Dictionary with Apple Ads attribution details. Omitted when Qonversion has no Apple attribution response for the user or Apple has never attributed the user. See Apple Ads attribution fields.

Revenue and price fields

There are 3 fields that contain transaction details:

The revenue field contains a dictionary with details depending on your integration setting Send sales as proceed.
The price field always contains a gross price that is charged to a user.
The transaction field contains params of the transaction related to the event.

Revenue

Column	Required	Description
value	yes	Value in user’s currency
value_usd	yes	Value in USD
currency	yes	Three-letter ISO currency code
is_proceed	yes	1 – if `value` and `value_usd` are net excluding app stores’ commission; 0 - if values are before deducting app stores commission;
proceeds_rate	yes	70 or 85; Proceeds rate that developer receives after deducting app stores commission.

Price

Column	Required	Description
value	yes	Value in user’s currency
value_usd	yes	Value in USD
currency	yes	Three-letter ISO currency code

Transaction

Column	Required	Description
transaction_id	yes	Transaction_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
original_transaction_id	yes	Transaction_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
expires	yes	Expire timestamp for purchase, prolong or product change events, event timestamp for refund or upgrade events.
grace_period_expires	yes	Grace period expiration timestamp. Always present, but non-null only on the two billing-retry events, Trial Billing Retry and Subscription Billing Retry; every other event carries the key with a `null` value.
transaction_date	yes	Timestamp when the transaction was made.
promo_offer_id	no	App Store identifier of the offer applied to this transaction — a promotional offer, an offer code, or a win-back offer. `null` when no such offer applied, and absent from events that carry no transaction. Google Play does not use this field: the applied offer is part of the top-level `product_id`, formatted `productId:basePlanId:offerId`.

For the Billing Issue, Trial Canceled, Subscription Canceled, Subscription Upgraded events, the transaction_id field will be the same as for the previous related event. For the Subscription Renewed, Subscription Product Changed events, we’re sending a newer transaction_id.

Apple Ads attribution fields

Your app must first collect Apple Ads attribution with the Qonversion SDK by calling collectAppleSearchAdsAttribution() — see Collect Apple Ads attribution; an Apple Ads account connection is not needed for this. Events of attributed users then carry the asa_attribution object, which reflects the most recent Apple response that attributed the user (a later attribution=false answer does not remove it). Keys whose value is empty or missing are left out rather than sent as null. The data in the table below can be found in the asa_attribution field.

{
  ...
  "asa_attribution": {
    "org_id": 1234567890,
    "campaign_id": 1234567890,
    "adgroup_id": 1234567890,
    "keyword_id": 1234567890,
    "ad_id": 1234567890,
    "country_or_region": "DE",
    "conversion_type": "Download",
    "click_date": "2024-08-21T16:10Z",
    "impression_date": "2024-08-21T16:10Z",
    "claim_type": "Impression",
    "supply_placement": "APPSTORE_SEARCH_RESULTS"
  }
}

Column	Required	Description
org_id	no	The identifier of the Organization or Campaign group Id that owns the campaign.
campaign_id	no	The unique identifier for the campaign.
adgroup_id	no	The identifier for the ad group.
keyword_id	no	The identifier for the keyword. Left out when Apple sends no keyword, for example for Search Match.
ad_id	no	The identifier representing the assignment relationship between an ad object and an ad group. Left out when Apple sends no ad identifier; Apple’s placeholder `-1` is sent as is.
country_or_region	no	The country or region for the campaign.
conversion_type	no	The type of conversion is either Download or Redownload.
click_date	no	The date and time when the user clicks an ad in a corresponding campaign. Left out when Apple does not send it.
impression_date	no	The date and time when an ad view occurs in a corresponding Apple Ads campaign. Left out when Apple does not send it.
claim_type	no	The type of claim is either Impression or Click. Left out when Apple does not send it.
supply_placement	no	Where in the App Store the ad was shown, as Apple sent it. Left out when Apple does not send it.

Every key inside asa_attribution is optional: a key is left out whenever Apple’s value is empty or missing, so check for presence before reading it. Learn more about fields from Apple AdServices documentation.

Retries between Qonversion and Destination Server

Qonversion increases the delivery rate to your server with retries. Retries happen automatically when your server times out, is unreachable, or returns a non-2xx status — except 401, 403 and 404, which are treated as permanent and are not retried. This substantially improves the data delivery rate. After the initial attempt fails, Qonversion schedules up to five retries spread over roughly 24 hours; if the last one fails too, the event is not delivered. You can review delivery attempts from the last 7 days in the Delivery Log tab of the Webhooks integration. Retries have the following schedule (delay measured from the previous attempt):

Attempt	Delay since previous	Approx. time since first attempt
1	Immediate	0
2	1 minute	~1 minute
3	5 minutes	~6 minutes
4	~3 hours 55 minutes	~4 hours
5	4 hours	~8 hours
6	16 hours	~24 hours

Because a retry re-sends the event that already failed, your endpoint can receive the same event more than once — for example when your server processed a request but the response never reached us. Every attempt carries the same id, and so does a delivery you trigger yourself with the Resend action in the dashboard Delivery Log. Treat id as the idempotency key: record the ones this endpoint has already handled and ignore a repeat, scoping that record per integration, because a second Webhooks integration on the same app receives its own copy of the event under the same id.

Tenjin Refund Keeper

Apple Ads

Remote Configs + A/B Tests

Data and infrastructure

Integrations

Platform resources

No-Code Builder

SDK migration guides

1. Set up the webhook URL

Sandbox webhook URL

2. Request format

SSL certificate

Revenue and price fields

Revenue

Price

Transaction

Apple Ads attribution fields

Retries between Qonversion and Destination Server

​1. Set up the webhook URL

​Sandbox webhook URL

​2. Request format

​SSL certificate

​Revenue and price fields

​Revenue

​Price

​Transaction

​Apple Ads attribution fields

​Retries between Qonversion and Destination Server

1. Set up the webhook URL

Sandbox webhook URL

2. Request format

SSL certificate

Revenue and price fields

Revenue

Price

Transaction

Apple Ads attribution fields

Retries between Qonversion and Destination Server