Postback URL parameters guide: make every conversion event auditable

Postback URL parameters guide: make every conversion event auditable in brief

Postback URL parameters are the identifiers and instructions that make performance tracking reliable when traffic moves from click → conversion → payout.
On KiwiWall, they are the bridge between what happened on publisher traffic and what appears in advertiser and publisher reporting.
If your S2S postback URLs are missing required IDs, mixed parameter naming, or have mismatched dedupe rules, you create blind spots: delayed payouts, rejected events, and disputes you cannot prove.

Use a strict parameter map (click ID, transaction ID, sub IDs, optional campaign fields) in a consistent order, route through a dedicated event endpoint, and enforce replay-safe handling on both sides.
Then verify with acceptance checks: every click should map to one conversion path, every conversion should match exactly one payout record, and all errors should be auditable with reason codes.

This page is for people launching or maintaining KiwiWall performance integrations that depend on postback integrity.

For context and adjacent KiwiWall resources, start at the parent hub: performance tracking and fraud control.

Who this is for

This guide is for:

• Publishers adding KiwiWall offerwalls who need auditable revenue reporting.
• Advertisers running CPA/CPL/CPI campaigns and needing reliable conversion event handoff.
• Technical teams maintaining conversion pipelines for offer routing, reporting, and reconciliation.

It is also practical for growth operators who translate campaign performance into scaling decisions.

Definition

A postback URL is a machine-readable HTTP request sent from one system to another when a conversion-related event occurs (for example, install, signup, form submission, deposit, or first purchase).
In KiwiWall setups, the URL typically carries:

• an event outcome (status, payout, revenue),
• identifiers (click_id, txn_id, sub1...sub5),
• optional traffic/context metadata (geo, device, placement, campaign),
• and authentication elements (signature, timestamp).

The reason this matters is simple: if those parameters are incomplete or inconsistent, every report you produce becomes a hypothesis rather than an audit trail.

For technical clarity, we separate:

• Click-level identity (where traffic started),
• Transaction-level identity (what action was claimed),
• Segmentation fields (how to group and compare traffic quality),
• and control fields (dedupe, security, and error context).

Decision table

Use this table as a first-pass planning tool before build.

When this applies

• Multi-party traffic flows where publisher and advertiser need the same conversion event language.
• Campaigns where payout disputes happen or data quality is difficult to prove.
• Any integration with more than one tracking boundary (ad platform, offer wall, landing page, conversion endpoint).

When this does not apply

• One-off trials with no reconciliation requirement.
• Single-offer experiments where dashboards are only used for rough directional insights.
• Teams that cannot keep parameter contracts stable and do not want to support event-level QA.

How it works

Think of postback URL parameterization as a 5-stage flow:

1) Define a canonical parameter contract

Start by publishing a single contract that both KiwiWall and your internal stack accept:

• fixed parameter names,
• required/optional status list,
• max length and allowed values for each field,
• timezone and date formatting standards,
• security method.

2) Generate stable identifiers at click

At click time, assign and persist:

• click_id for the interaction source,
• optional sub fields for business segmentation (sub1 geo, sub2 placement, sub3 publisher source, sub4 campaign phase, etc.),
• campaign and creative context.

Do not reuse identifiers across unrelated placements. Reuse creates false joins during dedupe and skews postback quality analysis.

3) Carry IDs through all redirects

Keep IDs in query strings or equivalent signed payload fields long enough to survive:

• offer wall handoffs,
• landing page redirects,
• conversion callbacks.

If IDs can be dropped by a middle layer, map them to a canonical payload before leaving that layer.

4) Validate on postback endpoint

Your endpoint should:

1. verify signature/timestamp (if used),
2. normalize IDs (trim whitespace, consistent case),
3. run dedupe checks,
4. validate event state transitions,
5. write an error reason before returning failure.

If step 4 flags a mismatch, return failure codes consistently and include retriable semantics.

5) Reconcile both sides and document failure rules

Reconciliation should:

• match click_id + txn_id pairs before payout adjustments,
• compare advertiser/publisher totals by same status taxonomy,
• review rejection reasons by code,
• and keep runbooks for top failure classes.

Example scenario

You run a publisher + advertiser test for an install campaign in two geos.

1. A click is created with:
   • click_id: c_94f1f2,
   • sub1: us,
   • sub2: post-content-banner,
   • sub3: spring-test,
   • txn_id: set only at conversion.
2. User completes the offer.
3. KiwiWall sends a postback with:
   • status=approved,
   • click_id=c_94f1f2,
   • txn_id=t_7a8c1,
   • payout=2.35,
   • signature=....
4. The endpoint validates signature and stores the conversion event keyed to (click_id, txn_id).
5. The next day, reports show accepted conversion rate and rejection reasons by sub1, sub2, and source.

Without this parameter discipline, you might see “conversion happened” but fail to prove whether it belongs to us or ca, which placement drove quality, and whether rejection was temporary or systemic.

Related setup and troubleshooting references:

• S2S postbacks explained
• How to debug postback mismatches

Common mistakes

Mistake 1: Mixed parameter names across channels

Using sub_id, sub1, affiliate_sub interchangeably causes one-side parsing errors. Fix: lock one canonical map and version it.

Mistake 2: Missing dedupe rules

Without idempotency, retries can generate duplicate payouts or duplicated “accepted” states. Fix: dedupe key by click_id + txn_id + event_type and enforce exactly-one acceptance.

Mistake 3: No reason code discipline

“Failed” is too coarse when it hides root causes. Fix: emit rejection reason buckets (invalid_payload, already_processed, signature_mismatch, late_window, etc.).

Mistake 4: Different semantics between teams

If “approved” in advertiser logic means accepted-but-later-reviewed in publisher logic, reconciliations will be wrong. Fix: shared status contract and common transition rules.

Mistake 5: No rollback rule

When schema changes roll out, old parameters may arrive after new endpoint deployment. Fix: implement backward-compatible parser logic for a sunset period, and document migration cutover.

Checklist

Use this checklist before promoting a release:

• Parameter contract is documented, versioned, and signed off by both product/ops.
• Click IDs are generated once per click and never reused across placements.
• sub1...sub5 semantics are predefined and not changed per campaign ad hoc.
• Every conversion event includes transaction ID and status.
• Dedupe logic is idempotent with replay-safe behavior.
• Endpoint returns deterministic response codes and reason taxonomy.
• Rejection logs are retained long enough to support payout disputes.
• Reconciliation query compares click-source and conversion-side totals daily.
• At least one rollback/recovery plan exists for schema migration.
• A runbook exists for each top 3 rejection reasons.

If all items are not true, do not scale traffic on this build.

FAQ

What if txn_id is missing?

Treat it as a hard validation failure if your reporting depends on disputes and payout proof. If needed, create a temporary fallback identity key only for triage, and migrate to full transaction IDs quickly.

Do we need one postback URL per campaign?

No. You need one canonical event endpoint with campaign context in parameters. Use sub3/sub4 for campaign metadata and keep endpoint logic generic.

Does this hurt latency?

Adding validation adds millisecond-level processing, not campaign-level latency. Rejecting malformed payloads early is usually faster and safer than debugging false downstream matches later.

How do we reduce false rejections?

Tighten schema tests and signature checks in staging, validate encoding, and keep retry windows explicit (retry_after / max_retries) so partners know expected behavior.

Who should approve postback schema changes?

Product/ops for behavior impact, and technical owners for endpoint compatibility. Finance and revenue teams should approve payout implications only.

Evidence notes

This draft is aligned with:

• Obsidian strategy sync log for 2026-06-18 and the associated no-drift check in content-silo-strategy.md.
• Content silo run notes from KIW-89, including evidence references EVID-KS-20260618-1 through EVID-KS-20260618-5.
• Search guidance references in the current repo plan for this phase of AI-search-oriented technical content.

Conversion link

If your postback model is not clean yet, pause scaling and implement the checklist on this page first.
Then move to the KiwiWall conversion path with a setup that matches your traffic and payout design: Get started with KiwiWall.