> For the complete documentation index, see [llms.txt](https://docs.onside.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onside.io/api/store-attribution-webhooks.md).

# Store Attribution Webhooks

## Process Description

The attribution process is divided into five main stages:

1. **Initial Visit & Web Attribution**: \
   A user visits our landing page, triggering the `landing_page_visited` event. We log this visit, including their IP address and referrer information. When they click the "Install" button, the `install_button_tapped` event is fired, and we initiate the installation process.
2. **Marketplace Installation:**\
   Installing the marketplace on a device triggers the `store_app_installed` event.
3. **First Launch & Mobile Attribution**: \
   On first launch, the marketplace app registers itself with our backend. The backend attempts to match the mobile installation to the initial web visit using the user's IP address.
4. **User Verification & Final Attribution**: \
   When the user signs in and verifies their account, we create a user record and link it to the mobile installation and the original web visit. This completes the attribution chain.
5. **App Installation**: \
   The mobile app is installed on the user's device, which triggers the `app_installed` event.

## Delivery method

Onside sends attribution events as webhooks using an HTTPS POST request.

* Each event is delivered as a JSON payload following the schema below.
* You can get these events set up for your account by providing your webhook endpoint URL to your Onside account manager.

## Event structure

All events conform to the [schema](https://onside.io/schema/ads-conversions.json).

| Field             | Description                                                                                          | Required                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| onside\_event\_id | unique identifier for deduplication (uuid)                                                           | +                                                             |
| conversion\_label | type of event ([see below](https://docs.onside.io/api/store-attribution-webhooks#conversion-labels)) | +                                                             |
| conversion\_time  | RFC 3339 timestamp of when the event occurred                                                        | +                                                             |
| app\_id           | ApplicationApple Id (uint64)                                                                         | + for `conversion_label` = `app_installed` and `app_launched` |
| gclid             | Google Ads click identifier (from web campaigns)                                                     | -                                                             |
| gbraid            | Identifier for click-based attribution on iOS (Google Ads)                                           | -                                                             |
| wbraid            | Identifier for view-through attribution on iOS (Google Ads)                                          | -                                                             |

<details>

<summary>Event example</summary>

```json
[
  {
    "onside_event_id": "0197ac9c-ef28-7ee3-a5b4-533c6157d4d8",
    "conversion_label": "store_app_installed",
    "conversion_time": "2025-01-01T00:00:00Z",
    "app_id": "1234567890",
    "gclid": "EAIaIQobChMInbuctZO6jgMVEWWkBB2KrCZJEAEYASAAEgLVvfD_BwE",
    "gbraid": "0AAAAAqGACjk7bU-GTrGxRYpdqSonuTpAV",
    "wbraid": "0AAAAAqGACjmOugzfZ2SiPGY7nz370F-s-"
  }
]
```

</details>

### Conversion labels

The following conversion events are supported:

| Label                   | Description                                           | Comment                                                                               |
| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
| landing\_page\_visited  | User opened the landing page from an ad.              | This event is not available by default. Please ask your account manager to enable it. |
| install\_button\_tapped | User tapped the “install” button on the landing page. | This event is not available by default. Please ask your account manager to enable it. |
| store\_app\_installed   | User installed the Onside store app.                  |                                                                                       |
| app\_installed          | User installed the app via the Onside store.          |                                                                                       |
| app\_launched           | User opened the app.                                  | This event is only available when the Onside SDK is integrated into the app.          |

### Usage

* Events are sent via POST webhooks directly to the endpoint you provide.
* These events are exported to Google Ads for conversion tracking and optimization.
* Each event should include the `gclid`, `gbraid`, or `wbraid` parameter if available to ensure correct attribution.
* Events can be deduplicated using the `onside_event_id` field.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onside.io/api/store-attribution-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.