Postbacks & attribution

Partner docs are supply-side: they help offer providers understand what happens after AON serves an eligible offer. Use this page to align tracking click, conversion, and postback responsibilities.

Reach this step after the approved Partner has completed the Offer Fetch URL, credentials, and signed fetch test. The completion check below applies to the Provider path that reports conversions to AON; it does not require a Developer or Agent receiver webhook.

Current v1.0 source

The single current contract is the Postback specification, with its Provider request schema. This page covers only the Provider-to-AON onboarding path; do not copy it as a second field specification.

Provider quickstart: report a conversion to AON

Prerequisites: your Partner route is enabled, its source IP is allowlisted, and you have one attributed aon_click_id, aon_tracking_id, or offer_instance_id.

Send JSON POST /v1/postback/{partner_id} with exactly this version header; do not add a payload version, query parameters, form fields, or AppKey/AppSecret signature headers.

curl -X POST https://api.example.test/v1/postback/019f5f65-dbc1-7c3c-9ef9-9d6d2d8ae001 \
  -H "Content-Type: application/json" \
  -H "AON-Protocol-Version: 1.0" \
  -d '{
    "event_name": "purchase",
    "aon_tracking_id": "trk_123456",
    "event_id": "partner-event-42",
    "amount": "179.99",
    "currency": "USD"
  }'

The expected first success is a 2xx response with AON-Protocol-Version: 1.0, a closed response envelope, a result such as accepted, and a correlation id. Current 4xx responses are terminal: correct the method, headers, closed JSON body, attribution, or Goal mapping instead of retrying the same request. Both 500 and 503 are retryable AON-side failures. Retry them with backoff while preserving the same stable business identity (event_id, order_id, or partner_txn_id) across every attempt.

Developer callback handoff

Receiving an Agent or Developer conversion callback is not part of this Partner onboarding path. Use Developer Webhooks for the current receiver contract, required headers, raw-body verification, idempotency, retry schedule, and failure handling.

Attribution flow

The high-level flow is:

1. AON fetches eligible offers from your Offer Fetch endpoint.
2. A user follows a tracked offer link.
3. The click is resolved and attribution context is preserved.
4. A conversion or partner postback reconciles the outcome.

The Partner page explains where your systems fit in that flow. The API Reference remains the source for endpoint-specific request and response details.

What partners own

Partners usually own:

• Landing page redirect integrity after a tracked click.
• Conversion event quality and dedupe logic in their own systems.
• Retry handling and observability for server-to-server callbacks.
• Reconciliation logs that preserve request or tracking identifiers.

Keep logs tied to your Offer Fetch request_id and downstream attribution records so support teams can connect offer serving, clicks, and conversions.

When to use API Tracking docs

Use API Tracking when you need endpoint-level details for click redirects, conversion events, or partner postback callbacks. Do not copy those fields into Partner onboarding notes; link to the API Reference so the contract stays in one place.

Test and reconciliation checklist

• Confirm test traffic cannot trigger real billing, fulfillment, or inventory side effects.
• Keep retry behavior idempotent for conversion and postback handling.
• Log enough context to reconcile click, conversion, and Partner account state.
• Review operational settings in Partner Portal Setup.

Partner document-path completion

The Partner document path ends here when the Provider click/postback test has evidence, conversion handling is idempotent, and reconciliation can connect Offer Fetch, clicks, and conversion records. This is document-path completion, not a live approval: this docs-path step is not live. ready_for_review only means the integration can be submitted for review. Call the Partner live only after it is approved and its production health is healthy. A Developer or Agent receiver webhook is not a Partner readiness requirement.

Current v1.0 response and failure semantics

POST /v1/postback/{partner_id} with AON-Protocol-Version: 1.0 uses the HTTP status code as the primary success/failure signal. Alert and retry logic should key off the status code first; treat the closed response body as supporting detail, not the thing you branch on.

All current 4xx/5xx envelopes keep data exactly {}. Diagnostics live in extra, including result, reason, correlation_id, retryable, and event_logged.

Rejection body examples

Current POST /v1/postback/{partner_id} failure:

{
  "code": "INVALID_PAYLOAD",
  "message": "invalid_payload",
  "data": {},
  "extra": {
    "result": "rejected",
    "reason": "invalid_payload",
    "correlation_id": "<journal_id>",
    "retryable": false,
    "event_logged": false
  }
}

Compatibility routes

GET /v1/postback/{partner_id} and the query/form shapes remain compatibility routes for existing integrations. They are not current v1.0 entrypoints, do not silently promote to the current contract, and keep their existing auth and response behavior.

Integration recommendations

• Alert on any non-2xx response from either endpoint — a response is not the same thing as a recorded conversion.
• Treat 5xx and 503 as retryable: 503 means AON is temporarily unavailable (retry with backoff), and 5xx means an AON-side processing failure where standard HTTP retry semantics apply safely because retries are idempotent.
• Do not resend a 4xx-rejected payload unmodified — inspect the reason and fix the payload or event mapping before sending again.
• Validate the response body code field explicitly; do not infer success from response shape alone.

Compatibility inbound security boundary

Compatibility GET /v1/postback/{partner_id} uses the configured Partner route, enablement, and IP allowlist. Do not add AppKey/AppSecret HMAC, timestamp, nonce, or signature headers to the callback. AppKey/AppSecret are reserved for AON's outbound Offer Fetch requests; see Credentials & signing.

Historical HMAC configuration does not add an inbound signature requirement on any postback lane.

Related pages

• Offer Fetch
• Partner Portal Setup
• API Tracking

If your landing URL template needs AON to insert a tracking value, review Tracking Macros. Otherwise, there is no additional Partner onboarding step after Postbacks & Attribution.