Postback Setup

Flow

End user clicks an offer in the Preads wall
        |
        v
Preads records the click  (GET /api/track)
        |
        v
The offer network completes the conversion
        |
        v
The network calls Preads   (ANY /api/postback)
        |
        v
Preads verifies the click, calculates rewards,
credits your balance, writes the conversion row
        |
        v
Preads calls YOUR postback URL   (GET, once)

Your postback is a notification, not a confirmation. The conversion is recorded and your balance is credited before your postback is sent. If your endpoint is down, the conversion still counts — you simply miss the notification.

Configuration

The postback URL is set per app, so each of your apps can notify a different endpoint.

1. Open Publisher → Apps and select your app.
2. Set Postback URL.
3. Save. The URL is validated when you save it and re-checked immediately before each request is sent.

URL rules

• Must be http:// or https://.
• Must resolve to a public address. Loopback and private ranges (127.0.0.0/8, 10.0.0.0/8, 192.168.0.0/16, 169.254.0.0/16, and similar) are rejected. The literal host localhost is the one exception, so it works in development.
• A blocked URL is not retried. The attempt is recorded as failed with the message "Blocked: postback URL is not a public http(s) address".
• There is no placeholder for the app ID or the app's currency. If you need them, hardcode them into each app's URL, or use the {user_id} you already control.

Macro reference

Macros in your postback URL are replaced with conversion values. Place them anywhere in the query string.

Every macro except {status} is URL-encoded before substitution. All values are therefore safe to read directly from $_GET / request.query without further decoding.

Macro semantics — read before crediting users

{offer_id} is a network ID

{offer_id} resolves to the offer's network ID. It is not the offerId you passed to GET /api/track, and it is not unique per offer — every offer from the same network shares it. If you reconcile conversions against offers in your own reporting, use {offer_name} or the network ID knowingly; there is no macro that gives you the offer ID.

{payout} and {reward} vary by network type

These two macros read the same two database columns for every conversion, but the platform writes those columns differently depending on how the conversion arrived:

There is no macro that returns the end user's reward consistently across both network types. If you need a reliable per-conversion breakdown, reconcile against the conversion you received (using {transaction_id}) rather than inferring it from the amount fields.

Example

A postback URL for a rewards endpoint:

https://api.example.com/rewards?uid={user_id}&txn={transaction_id}&offer={offer_name}&amount={reward}&status={status}&camp={aff_sub}

A request Preads sends for an approved conversion:

GET /rewards?uid=user_8812&txn=clk_68f2a1b0c3d4e5f6_a1b2c3d4e5f60718&offer=Complete+a+signup&amount=1.2500&status=approved&camp=summer_promo

Delivery behaviour

Verifying delivery

Every attempt is recorded. Open Publisher → Reports → Postbacks to see the resolved URL, the HTTP status code, the first 1000 characters of your response body, and the error message when one occurred. The page also reports total, successful, failed and success-rate figures.

Testing your postback

Each app has a test tool: Publisher → Apps → your app → Postbacks. It lets you send a test postback with a chosen user_id and amount, re-send a previous test, simulate a network rejection, view the fully substituted URL before sending, and delete tests.

Test conversions are stored separately and are excluded from every figure in your dashboard, so sending tests will not distort your reports. Test postbacks carry {status}=approved unless you explicitly reject them, and their {transaction_id} is prefixed TEST_ — reject those in your own handler.

Which conversions trigger a postback

Outbound postbacks are sent for offerwall conversions only. The behaviour differs by source:

Locker conversions are recorded and appear in your reports and statistics, but they are written with no app association and no outbound postback is ever sent for them. If you run a locker, do not build a crediting flow on postbacks — use the locker's statistics page or poll its progress endpoint instead.

Inbound: networks → Preads

For completeness: the endpoint offer networks post to is https://preads.hansaldev.com/api/postback (any HTTP method, rate-limited to 300 requests/minute per IP). It is unauthenticated by design, because third-party networks cannot be expected to sign requests.

It resolves the click ID from any of these parameters:

click_id, subId, subid, aff_sub, aff_sub1, s2, transaction_id, txn_id, tid

Responses:

Any payout, amount or reward figure a network sends is ignored. The platform uses its own offer record, so a network cannot credit itself.

Troubleshooting

Related documentation

• Offerwall Iframe — supplying userId and the aff_sub sub-parameters that come back here.
• App/Website Setup — where the postback URL is set.
• API Access — the API-key authentication used by the tracking endpoint.