> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks (COPY)

> Send in-app subscription and purchase events to your server with 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](/docs/check-permissions) 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.

<img src="https://mintcdn.com/qonversion/5c527iOH0vIMjiW3/images/docs/ce45d70-Webhooks_integration.png?fit=max&auto=format&n=5c527iOH0vIMjiW3&q=85&s=342c6ad061396b90420f39274203053e" alt="" width="3432" height="1682" data-path="images/docs/ce45d70-Webhooks_integration.png" />

## 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:**

```json theme={null}
Authorization: Basic {Header Authorization-Token}
Accept: application/json
```

**Request Body:**

```json theme={null}
{
   "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
   },
   "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",
   "old_product_id": "com.myapp.subs.4.99.trial",
   "new_product_id": "com.myapp.subs.9.99.trial",
}
```

<table>
  <thead>
    <tr>
      <th>
        Column
      </th>

      <th>
        Required
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        event\_name
      </td>

      <td>
        yes
      </td>

      <td>
        Event name provided in the integration config.\
        See the details on the events tracked [here](/docs/integrations-overview)
      </td>
    </tr>

    <tr>
      <td>
        user\_id
      </td>

      <td>
        yes
      </td>

      <td>
        Unique user identifier assigned by Qonversion
      </td>
    </tr>

    <tr>
      <td>
        custom\_user\_id
      </td>

      <td>
        yes
      </td>

      <td>
        Unique user identifier that you can set with Qonversion SDK methods: [User Identifiers](/docs/user-identifiers#logging-in)
      </td>
    </tr>

    <tr>
      <td>
        identity\_id
      </td>

      <td>
        yes
      </td>

      <td>
        Unique user ID for the authenticated users that you can set using <a href="/docs/user-identifiers#3-user-identity" target="_blank" rel="noopener">identify method</a> of the Qonversion SDK
      </td>
    </tr>

    <tr>
      <td>
        advertiser\_id
      </td>

      <td>
        yes
      </td>

      <td>
        IDFA or AAID
      </td>
    </tr>

    <tr>
      <td>
        time
      </td>

      <td>
        yes
      </td>

      <td>
        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 time [here](/docs/integrations-overview#event-time)
      </td>
    </tr>

    <tr>
      <td>
        created\_at
      </td>

      <td>
        yes
      </td>

      <td>
        The time Qonversion generated the event
      </td>
    </tr>

    <tr>
      <td>
        product\_id
      </td>

      <td>
        yes
      </td>

      <td>
        App Store or Google Play Store product identifier
      </td>
    </tr>

    <tr>
      <td>
        revenue
      </td>

      <td>
        yes
      </td>

      <td>
        Dictionary with transaction revenue details. Only events with value filled
      </td>
    </tr>

    <tr>
      <td>
        price
      </td>

      <td>
        yes
      </td>

      <td>
        Dictionary containing the price details of the product
      </td>
    </tr>

    <tr>
      <td>
        transaction
      </td>

      <td>
        yes
      </td>

      <td>
        Dictionary with store transaction IDs and expiration timestamp
      </td>
    </tr>

    <tr>
      <td>
        properties
      </td>

      <td>
        yes
      </td>

      <td>
        User properties provided by SDK. Read more about user properties [here](/docs/user-properties)
      </td>
    </tr>

    <tr>
      <td>
        device\_id
      </td>

      <td>
        yes
      </td>

      <td>
        identifierForVendor or Settings Secure Android ID
      </td>
    </tr>

    <tr>
      <td>
        app\_version
      </td>

      <td>
        no
      </td>

      <td>
        Application version
      </td>
    </tr>

    <tr>
      <td>
        sdk\_version
      </td>

      <td>
        no
      </td>

      <td>
        Qonversion SDK version
      </td>
    </tr>

    <tr>
      <td>
        environment
      </td>

      <td>
        yes
      </td>

      <td>
        "production" or "sandbox"
      </td>
    </tr>

    <tr>
      <td>
        platform
      </td>

      <td>
        yes
      </td>

      <td>
        "iOS" or "Android"
      </td>
    </tr>

    <tr>
      <td>
        ip
      </td>

      <td>
        yes
      </td>

      <td>
        Application device IP address
      </td>
    </tr>

    <tr>
      <td>
        country
      </td>

      <td>
        yes
      </td>

      <td>
        A two-letter code representing a country, defined by the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard
      </td>
    </tr>

    <tr>
      <td>
        old\_product\_id
      </td>

      <td>
        no
      </td>

      <td>
        Previous product (for product change events)
      </td>
    </tr>

    <tr>
      <td>
        new\_product\_id
      </td>

      <td>
        no
      </td>

      <td>
        New product (for product change events)
      </td>
    </tr>
  </tbody>
</table>

## 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

<table>
  <thead>
    <tr>
      <th>
        Column
      </th>

      <th>
        Required
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        value
      </td>

      <td>
        yes
      </td>

      <td>
        Value in user's currency
      </td>
    </tr>

    <tr>
      <td>
        value\_usd
      </td>

      <td>
        yes
      </td>

      <td>
        Value in USD
      </td>
    </tr>

    <tr>
      <td>
        currency
      </td>

      <td>
        yes
      </td>

      <td>
        Three-letter ISO currency code
      </td>
    </tr>

    <tr>
      <td>
        is\_proceed
      </td>

      <td>
        yes
      </td>

      <td>
        1 – if `value` and `value_usd` are net excluding app stores' commission;\
        0 - if values are before deducting app stores commission;
      </td>
    </tr>

    <tr>
      <td>
        proceeds\_rate
      </td>

      <td>
        yes
      </td>

      <td>
        70 or 85; Proceeds rate that developer receives after deducting app stores commission.
      </td>
    </tr>
  </tbody>
</table>

### 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

<table>
  <thead>
    <tr>
      <th>
        Column
      </th>

      <th>
        Required
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        transaction\_id
      </td>

      <td>
        yes
      </td>

      <td>
        Transaction\_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
      </td>
    </tr>

    <tr>
      <td>
        original\_transaction\_id
      </td>

      <td>
        yes
      </td>

      <td>
        Transaction\_id from App Store (e.g. 521456677817903) or Play Store (e.g. GPA.4563-9870-7648-87395)
      </td>
    </tr>

    <tr>
      <td>
        expires
      </td>

      <td>
        yes
      </td>

      <td>
        Expire timestamp for purchase, prolong or product change events, event timestamp for refund or upgrade events.
      </td>
    </tr>

    <tr>
      <td>
        grace\_period\_expires
      </td>

      <td>
        yes
      </td>

      <td>
        Grace period expiration timestamp.\
        This field returns the timestamp for the grace period expiration.
      </td>
    </tr>
  </tbody>
</table>

> 🚧
>
> 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`.

## 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:

| Attempt | Delay       |
| :------ | :---------- |
| 1       | Immediately |
| 2       | 5 minutes   |
| 3       | 4 hours     |
| 4       | 8 hours     |
| 5       | 24 hours    |