# Postbacks & attribution

Source: https://docs.aon.pro/partner/postbacks

> Derived from the same AON Docs release as the source page.

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.

> Endpoint reference lives in API docs
>
> This page is an onboarding task guide. For endpoint-level request and response details, use [API Tracking](https://docs.aon.pro/api/tracking).

## Current v1.0 source

The single current contract is the [Postback specification](https://github.com/agentoffernetwork/protocol/blob/main/v1.0/specs/postback.md), with its [Provider request schema](https://github.com/agentoffernetwork/schema/blob/main/v1.0/json-schema/postback-partner-payload.json). 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.

```bash
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](https://docs.aon.pro/api/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](https://docs.aon.pro/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](https://docs.aon.pro/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.

| Segment | Meaning | Example reasons | Action |
| --- | --- | --- | --- |
| 2xx | Accepted, already recorded, or durably logged but unmapped | `accepted`, `already_recorded`, `unmapped` in `data.result` | No action needed |
| 4xx | Terminal request, security, identity, attribution, or Goal rejection | Stable lowercase reason in `extra.reason`; `extra.retryable: false` | Correct the request or integration before sending again |
| 500 | Pre-intake AON failure | `internal_error`; `extra.retryable: true` | Retry with backoff and preserve the same business identity |
| 503 | Current intake unavailable or durable processing deferred | `postback_v10_unavailable` or `postback_intake_unavailable`; `extra.retryable: true` | Retry with backoff |

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:

```json
{
  "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](https://docs.aon.pro/partner/credentials-signing).

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

## Related pages

-   [Offer Fetch](https://docs.aon.pro/partner/offer-fetch)
-   [Partner Portal Setup](https://docs.aon.pro/partner/portal-setup)
-   [API Tracking](https://docs.aon.pro/api/tracking)

If your landing URL template needs AON to insert a tracking value, review [Tracking Macros](https://docs.aon.pro/partner/tracking-macros). Otherwise, there is no additional Partner onboarding step after Postbacks & Attribution.