Server-to-server events

Send events to Appstack from your servers: purchases confirmed by your billing system, renewals and refunds from store notifications, or events from a web app. Server-to-server (S2S) events work alongside the Appstack SDK, or instead of it for teams that run enhanced app campaigns (EACs) without installing the SDK.

Authentication

Every request must include an Authorization header containing your Appstack API key, as is, with no Bearer prefix. You can find your API key in the Appstack dashboard under your app settings.

Authorization: <your-api-key>

The key selects the app and the environment:

The event is recorded for the app of the key. If platform names the other OS of the same project (for example android with your iOS app’s key), it is recorded for that project’s Android app.
A production key records production events. A development key records development events: use it to test your integration. Development events show in the Development view of the SDK page and in the Export API with a development key, and never reach your dashboards or your ad networks.

Track events (S2S)

Send a POST request to track installs, purchases, and other events:

curl --location 'https://api.event.appstack.tech/server-to-server/events' \
  --header 'Authorization: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "platform": "ios",
    "event_id": "1234567890",
    "appstack_id": "1234567890",
    "sdk_version": "custom_acme",
    "created_at": "2025-01-15T14:32:08Z",
    "event_name": "START_TRIAL",
    "event_type": "CUSTOM",
    "trigger_type": "MANUAL",
    "parameters": {
      "price": 8.99,
      "currency": "USD",
      "email": "abc.def@appstack.tech",
      "phone_number": "+33123445643"
    },
    "transaction_details": {
      "test": "transaction_test"
    },
    "attribution_details": {
      "campaignId": "1234567890",
      "conversionType": "CLICK"
    }
  }'

A valid request returns 200 with {"status": "success"}. The event is then processed asynchronously: it usually shows up in the SDK page within a few minutes.

Status	Description
`200`	Event accepted.
`401`	Missing or invalid `Authorization` header.
`422`	Invalid body, for example a missing or unknown `platform`, or a `created_at` that is not a valid timestamp.

Request body fields

Field	Required	Description
`platform`	Yes	App platform: `"ios"`, `"android"`, or `"web"`.
`event_id`	No	Client-generated unique ID for this event (unique per event).
`appstack_id`	No	Prefer the ID generated by the SDK when available. If you only use S2S and handle matching outside the SDK, generate a stable ID yourself — it must be unique per app install.
`sdk_version`	No	Static label for your integration, for example `CUSTOM_AcmeCorp`.
`created_at`	No	The time the event actually happened, as an ISO 8601 timestamp in UTC (for example `2025-01-15T14:32:08Z`). Defaults to the time Appstack receives the event. Handle with care — see Using `created_at` correctly.
`event_name`	Yes	Name of the event, for example `"PURCHASE"`. Keep it short (see Event name length). An event without a name cannot be used.
`event_type`	Recommended	`"STANDARD"` for the supported event names, `"CUSTOM"` otherwise.
`trigger_type`	Recommended	`"MANUAL"` for these API-driven events.
`parameters`	No	Key-value payload (for example `price`, `currency`, `productId`, `email`, `phone_number`). Revenue is read from `revenue`, `product_price` or `price`, and its currency from `currency`. Other values are stored encrypted.
`transaction_details`	No	Used for automatic events tied to the App Store.
`attribution_details`	No	Used for automatic events tied to Apple Search Ads (for example `campaignId`, `conversionType`).

Using `created_at` correctly

created_at tells Appstack when the event happened, not when your server sent it. Leave it out to use the time Appstack receives the event. Appstack uses it to place the event on the user’s timeline, relative to the install, the click, and the user’s other events. A wrong value can therefore silently corrupt attribution, ordering, and reporting, with no error returned by the API.

Only set created_at if you can guarantee it is accurate. A wrong timestamp is worse than a late event: the request still succeeds, but the event can be attributed, ordered, or reported incorrectly.

A created_at more than 1 hour in the past is replaced by the time Appstack receives the event, so that late events still reach your dashboards and ad networks. Send events as soon as they happen.

Events are not always sent in real time. Your backends often receive events with a delay: webhooks from App Store / Google Play / your billing provider, retries after a failure, queues, batch jobs, or nightly syncs. In these cases, the moment you call the Appstack API is not the moment the event occurred.

Use the original event time. Take the timestamp from the source of truth (the store notification, your billing provider, your database record), never from now() at send time.
Always send UTC, in ISO 8601 with an explicit Z suffix (or offset). A timestamp without a timezone, or a local time labelled as UTC, shifts the event by hours and can move it before the install or into the wrong day.
Never send a future date. Check clock skew on your servers, and watch for seconds vs. milliseconds mix-ups when converting epoch values.
Never hardcode or reuse a placeholder (such as the sample value in the request above). Every event must carry its own timestamp.
Keep events consistent. An event should not be dated before the install it belongs to, and a retry of the same event (same event_id) must keep the same created_at as the first attempt.
Replays and backfills: events older than 1 hour are recorded at the time they are received (see above), so the API is not suited to backfilling history. Contact Appstack before replaying past events.

If your pipeline cannot give you a reliable original event time, ask yourself whether you should send created_at at all, and validate the values in a test environment before going live.

Event name length

Keep event_name short and simple. Events are forwarded to advertising networks, and these networks enforce their own limits on event names. For example, Meta rejects events whose names are too long, so an overly long name may never reach the network and the conversion will not be reported there.

Use a concise identifier such as START_TRIAL or PURCHASE, not a sentence or a description.
Don’t embed dynamic data (IDs, product names, dates, user info) in the name. Send them in parameters instead.
Stick to letters, digits, and underscores, and keep the naming consistent across events.

Supported event names

Use event_type: "STANDARD" with the appropriate event_name. The following standard event names are supported: SDK events (shared with in-app SDK and S2S): User acquisition

LOGIN
SIGN_UP
REGISTER

Monetization

PURCHASE
ADD_TO_CART
ADD_TO_WISHLIST
INITIATE_CHECKOUT
START_TRIAL
SUBSCRIBE

Games / progression

LEVEL_START
LEVEL_COMPLETE

Engagement

TUTORIAL_COMPLETE
SEARCH
VIEW_ITEM
VIEW_CONTENT
SHARE

S2S-only events (server-to-server only):

TRIAL_CONVERTED
SUBSCRIPTION_RENEWED
REFUND
INTRO

Any event name not listed above will be treated as a custom event. Custom events are tracked and visible in your dashboard but are not counted toward revenue metrics.

Revenue computation

The following events are used for revenue calculation:

TRIAL_CONVERTED
SUBSCRIBE
PURCHASE
SUBSCRIPTION_RENEWED
REFUND
INTRO

For REFUND events, the amount (price or revenue in the parameters object) must be negative (e.g., -9.99 for a refund of $9.99), with its currency.

Matching (click ↔ install)

To associate an install with a click, the app sends a request to the deeplink match endpoint. Replace {app_id} and {appstack_id} with your values:

curl --location --globoff 'https://appstack.link/deeplink/match/{app_id}?appstack_id={appstack_id}'

Call this endpoint from the user’s device, not from your servers. Matching relies on the information the request carries automatically from the device (such as its IP address): a request sent from your backend carries your server’s details and never matches.

Planned: parameter-based matching

Appstack intends to support server-side matching where an intermediary server can run matching by sending explicit signals (for example user IP, city and region (country), and coordinates). That option is not available yet; until it ships, rely on automatic device-side data collection as described above.

Personalize the user experience with attribution params

When a match succeeds, the deeplink match response returns the attribution params describing where the user came from (ad network, campaign, ad set, keywords, click IDs, and the raw network parameters). If you use the Appstack SDK instead of calling the match endpoint directly, you can read the same payload with getAttributionParams() (see the React Native, Swift, Kotlin, and Flutter SDK pages). Use these params to tailor the experience as early as the first launch, for example:

Show a campaign-specific onboarding or welcome screen based on appstack_campaign / appstack_ad.
Select a paywall variant or offer based on the acquisition source (appstack_adnetwork, media_source).
Pre-fill or theme content from the matched keywords (appstack_keywords).
Forward the params to partners (Superwall, RevenueCat, …) as user attributes for campaign filters.

Parameters returned by the match request / `getAttributionParams()`

The params are grouped into normalised Appstack values, a standard UTM value, the network click IDs, and the raw per-network parameters. Availability depends on the matched network and the data the click carried.

Group	Parameters
Normalised Appstack params	`appstack_adnetwork`, `appstack_campaign`, `appstack_adset`, `appstack_ad`, `appstack_keywords`, `appstack_id`
Standard link params	`media_source`, `campaign_name`
Network click IDs	`fbclid`, `gclid`, `wbraid`, `gbraid`, `ttclid`
Meta cookies	`fbp`, `fbc`
Meta (raw)	`campaign_id`, `campaign_name`, `adset_id`, `adset_name`, `adsetname`, `adsetid`, `ad_id`, `ad_name`, `adname`, `adid`, `site_source_name`
Google (raw)	`campaignid`, `adgroupid`, `adgroup`, `adgroup_name`, `creative`, `keyword`, `keywords`, `keywordid`
TikTok (raw)	`cid`, `cid_name`, `aid_id`, `aid_name`, `adid_v2`, `adid_v2_name`
Your own link params	any custom parameter registered on a standard link at creation time

appstack_adnetwork is one of google, meta, tiktok, openai or x_ads, and is absent when the click carried no recognised network parameter. Any other parameter appended to the click URL is dropped, including utm_* and placement.

Prefer the normalised Appstack params (appstack_*) for personalization logic — they are consistent across networks. Fall back to the raw per-network parameters only when you need a value that isn’t covered by the normalised set.

A no-match response returns deeplink_id: "" and query_params containing only the appstack_id you sent. The endpoint echoes appstack_id back on every response, so non-empty query_params is not proof of attribution. Use a non-empty deeplink_id as the match check. The attribution fields are optional and only worth inspecting once the match is confirmed — a matched standard link, for example, returns media_source and campaign_name but no appstack_adnetwork.

Mobile SDKs

HTTP API

Server-to-server events

Authentication

Track events (S2S)

Request body fields

Using `created_at` correctly

Event name length

Supported event names

Revenue computation

Matching (click ↔ install)

Planned: parameter-based matching

Personalize the user experience with attribution params

Parameters returned by the match request / `getAttributionParams()`

​Authentication

​Track events (S2S)

​Request body fields

​Using created_at correctly

​Event name length

​Supported event names

​Revenue computation

​Matching (click ↔ install)

​Planned: parameter-based matching

​Personalize the user experience with attribution params

​Parameters returned by the match request / getAttributionParams()

Authentication

Track events (S2S)

Request body fields

Using `created_at` correctly

Event name length

Supported event names

Revenue computation

Matching (click ↔ install)

Planned: parameter-based matching

Personalize the user experience with attribution params

Parameters returned by the match request / `getAttributionParams()`