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. Webhook events are delivered within 20 to 120 seconds of the event occurring. Please consider using checkEntitlements method of Qonversion SDK to get real-time subscription status on the client-side.

1. Set up the webhook URL

1. Navigate to the Integrations section in your Qonversion account and select Webhooks.
2. Register your URL and Qonversion will send a request
3. Press the "Add new integration" or "Save" button. If the endpoint server returns a 200 response code, the integration is activated.

2. Request format

Qonversion sends POST request to webhook URL every time an event occurs. The request header contains Authorization-Token Value as Basic authorization field. Use that 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:

{
    "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",
    "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
    },
    "properties": {
        "_q_email": "[email protected]"
    },
    "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",
    "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,
    "entitlements": [
        {
            "active": true,
            "expires": 1654215637,
            "id": "plus",
            "product": {
                "product_id": "main",
                "subscription": {
                    "current_period_type": "normal",
                    "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"
    }
}

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

Price

Transaction

🚧

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 Downgraded, Subscription Product Changed events, we're sending a newer transaction_id.

Apple Search Ads attribution fields

You need to set up Apple Search Ads integration first, then we will send ASA attribution with all new events for only attributed users. 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"
  }
}

Learn more about fileds from Apple AdSevices documentation.

Retries between Qonversion and Destination Server

Qonversion increases the delivery rate to your server with retries. Retries happen automatically if your server is not responding. This substantially improves the data delivery rate.
Qonversion retries failed destination calls for 24 hours with an increased delay after each attempt. Retries have the following schedule: