CPA Postback API

Postback API for CPA network integrations — track installs, registrations, and deposits with auto-numbering

Overview

The Postback API allows CPA networks and affiliate platforms to send conversion events (install, registration, deposit) to Notify Partners. Each postback creates or updates a device record, fires event triggers, and can activate Push Packs tied to that event.

Endpoint:

GET /postback
POST /postback

Both methods are supported. GET is recommended for CPA networks (simple URL redirect), POST for server-to-server integrations.

Rate limit: 100 requests per IP address per second.

Parameters

Parameter	Required	Description
`app_id`	Yes	Your application ID (integer)
`token`	No	Postback token for authentication. Found in app settings. If provided, must match the app's postback token
`external_id`	No	External user identifier from CPA network (click ID, sub ID, etc.). If a device with this ID doesn't exist, it will be created automatically
`install_id`	No	Alias for `external_id`
`gaid`	No	Google Advertising ID — alias for `external_id`
`idfa`	No	Apple IDFA — alias for `external_id`
`event`	No	Event type: `install`, `reg`, `dep`, or any custom event
`segment`	No	User segment / audience (e.g., `vip`, `high_roller`)
`webmaster`	No	Webmaster / affiliate ID
`offer`	No	Offer / campaign ID

Priority for external_id: external_id > install_id > gaid > idfa. First non-empty value is used.

Note: If no external_id (or alias) is provided, the postback returns {"status": "ok"} but no device or event is recorded. Always include an identifier.

Parameter passing

GET — query string:

/postback?app_id=5&event=reg&external_id=click123

POST — form data or JSON body:

POST /postback
Content-Type: application/json

{
  "app_id": 5,
  "event": "reg",
  "external_id": "click123"
}

Deposit Auto-Numbering

When event=dep, the system automatically numbers repeated deposits for the same device:

Deposit #	Recorded event
1st	`dep`
2nd	`dep2`
3rd	`dep3`
4th	`dep4`
Nth	`depN`

This allows you to create different Push Packs for first deposit, second deposit, etc.

Example: A Push Pack with trigger event dep3 will fire only on the user's third deposit.

Responses

Success:

{"status": "ok"}

Errors:

Code	Response	Cause
400	`{"error": "app_id is required"}`	Missing `app_id` parameter
400	`{"error": "app_id must be a positive integer"}`	Invalid `app_id` format
401	`{"error": "invalid postback token"}`	Token doesn't match app settings
404	`{"error": "app not found"}`	App with this ID doesn't exist
403	`{"error": "app is archived"}`	App has been archived

CPA Network Integration Examples

Replace YOUR_APP_ID and YOUR_TOKEN with your actual values from the dashboard.

Pin-Up Partners

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={clickid}&event=reg

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={clickid}&event=dep

Macro	Description
`{clickid}`	Pin-Up click ID

1win Partners

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={uid}&event=reg&webmaster={pid}

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={uid}&event=dep&webmaster={pid}

Macro	Description
`{uid}`	1win user/click ID
`{pid}`	Partner / webmaster ID

Vavada Partners

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={click_id}&event=reg&offer={offer_id}

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id={click_id}&event=dep&offer={offer_id}&webmaster={affiliate_id}

Macro	Description
`{click_id}`	Vavada click ID
`{offer_id}`	Offer / campaign ID
`{affiliate_id}`	Affiliate / webmaster ID

Generic CPA Template

For any CPA network, use this template and replace macros with your network's variables:

https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id=CLICK_ID_MACRO&event=EVENT_TYPE&webmaster=WEBMASTER_MACRO&offer=OFFER_MACRO&segment=SEGMENT_MACRO

Testing Postbacks

1. Send a test postback

curl "https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id=test_user_1&event=install"

Expected response:

{"status": "ok"}

2. Verify device was created

Check the Devices page in the dashboard — a new device with external_id = test_user_1 should appear.

3. Send registration and deposit events

# Registration
curl "https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id=test_user_1&event=reg"

# First deposit
curl "https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id=test_user_1&event=dep"

# Second deposit
curl "https://api.notify.partners/postback?app_id=YOUR_APP_ID&token=YOUR_TOKEN&external_id=test_user_1&event=dep"

4. Verify events

In the dashboard, check the device's events — you should see:

install
reg
dep (first deposit)
dep2 (second deposit, auto-numbered)

5. Verify Push Pack triggers

If you have Push Packs with event triggers (e.g., reg, dep), verify that pushes were queued after the postback.

How It Works

CPA Network → GET /postback → Notify Partners
                                    │
                                    ├── Find or create device
                                    ├── Save tags (segment, webmaster, offer)
                                    ├── Record event (with auto-numbering)
                                    ├── Fire conversion triggers
                                    └── Activate matching Push Packs

When a postback is received:

Device lookup — finds existing device by external_id, or creates a new one
Tags — saves segment, webmaster, and offer as device tags for audience targeting
Event — records the event (with deposit auto-numbering)
Triggers — fires conversion triggers and Push Pack event triggers
Logging — all postbacks are logged for debugging (visible in Activity Log)

On this page