Postbacks

Conversion postbacks (server-to-server)

You save a template URL in Settings → Publisher Settings. When a conversion is approved, LootHQ replaces the {macros} below with real values and calls your URL server-to-server. You choose the param names; just point each one at the macro you want.

https://your-site.com/postback?key=YOUR_SECRET&user_id={user_id}&tx={transaction_id}&points={points}&payout={payout}&currency={currency}&offer_id={offer_id}&offer_name={offer_name}&status={status}&event={event_id}

Start from that exact template, including {offer_id} and {status}. They cost you nothing and you will want both the first time you reconcile: without {offer_id} your reporting can't say which offer paid, and without {status} your handler has nothing to assert on. The placeholder in the Settings field shows this exact template; copy it in and save (the field itself starts empty). Settings checks this for you at save time: it warns (it never blocks the save) when your template is missing {status} or {offer_id}, or when you have saved a primary URL with no reversal URL alongside it.

// Example: Node.js / Express (plain JS, runs as-is under `node`)
// The param names below are the ones YOU chose in your template URL.
app.get("/postback", async (req, res) => {
  const { user_id, tx, points, payout, offer_id, currency, status } = req.query;
  const event = req.query.event || ""; // the conversion's goal id; empty on prize redemptions

  // 0) Auth – your template URL hard-codes &key=...; reject anything without it
  if (req.query.key !== process.env.LOOTHQ_POSTBACK_SECRET) {
    return res.status(403).send("forbidden");
  }

  // 1) Basic sanity checks
  if (!user_id || !tx) {
    return res.status(400).send("missing params");
  }

  // 2) Idempotency – credit each (tx, event) pair exactly once. On wall and
  //    Offers API conversions alike, tx is the CLICK id and repeats for
  //    every goal of a multi-goal offer; only the pair is unique per
  //    credit. On a prize redemption, event is "" and tx alone is unique,
  //    so the pair degrades to tx. For strict safety under concurrent
  //    duplicates (two retries landing at once), also add a UNIQUE INDEX on
  //    the (tx, event) columns; a findOne-then-create check alone still has
  //    a race window.
  const existing = await db.Conversions.findOne({ tx, event });
  if (existing) {
    return res.status(200).send("already processed");
  }

  // 3) Confirm the user belongs to a real account
  const user = await db.Users.findById(user_id);
  if (!user) {
    return res.status(200).send("unknown user");
  }

  // 4) Credit the user.
  //    Hosted wall → {points} is ALREADY in your currency (coins x your rate).
  //                  Credit it as-is. Do NOT credit {payout}, which is USD.
  //    Offers API  → no coins; {payout} is USD, convert it yourself.
  //    Test for "" and not for null: a macro we don't substitute on this
  //    channel arrives PRESENT AND EMPTY, so `points != null` is true on an
  //    Offers API postback and Number("") would credit 0.
  const amount = points !== undefined && points !== ""
    ? Number(points)
    : usdToYourCurrency(Number(payout));

  await creditUser(user_id, amount);

  // 5) Store the conversion for reporting
  await db.Conversions.create({
    tx,
    event,
    user: user_id,
    credited: amount,
    payoutUsd: payout != null ? Number(payout) : null,
    currency: currency || "USD",
    offerId: offer_id || null,
    status: status || "approved",
  });

  return res.status(200).send("ok");
});

Dedupe keys, per channel

More money is lost to the wrong dedupe key than to anything else in this guide. Too weak and retries double-credit; too strong and real credits are dropped with no error on either side. Every channel is in the table.

• On the primary URL, the pair is always safe. Prize redemptions send an empty {event_id}, so storing the ({transaction_id}, {event_id}) pair degrades to the transaction id alone there, so one dedupe rule covers every placement type you will ever run.
• On conversions, the pair is required. {transaction_id} is the click id on both integration types, and a milestone (CPE) offer credits once per goal on one click: each goal repeats the transaction id and changes the event id. Dedupe on the transaction id alone and goals 2..n are silently discarded.
• Retries never mint new identities. Every automatic retry and every manual Resend of a delivery reuses the exact same {transaction_id} and {event_id} as its first attempt, so the pair you stored keeps matching.
• Reversals dedupe on {event_id} alone. On that channel it is a per-delivery UUID, while {transaction_id} is the original conversion's id and repeats. See Handling reversals.

Delivery and retries

A postback attempt succeeds when your endpoint returns an HTTP 2xx status within 10 seconds. Anything else (a non-2xx status, a timeout, or a connection error) is retried automatically on a fixed schedule:

Each value is the wait before the NEXT attempt, so that's 7 retries, or 8 attempts in total, with the last landing about 41 hours after the first. Then we give up and mark the delivery failed. Every retry (and a manual Resend) reuses the exact same {transaction_id} and {event_id} from the first attempt, which is why idempotent processing matters.

Every attempt (HTTP status, latency, a response snippet, and a timestamp) is logged and visible in Publisher Dashboard → Postback Deliveries. Deliveries that are still retrying or have failed outright can be re-fired on demand with the Resend button, without waiting for or restarting the schedule. A Resend never uses up one of those 8 attempts: it's counted separately on the delivery row, and a delivery that is still retrying keeps its full remaining budget and its existing next-retry time. Resend (and each remaining scheduled retry) re-reads your current saved postback URL first, so correcting a broken endpoint in Settings fixes the deliveries already in flight instead of replaying the old address. Only the endpoint changes: the {transaction_id} and every other value are carried over untouched, so your idempotency check still sees the same transaction.

If deliveries to one of your postback endpoints fail 3 or more times within 6 hours, we'll email you (at most once per 24h per endpoint) with which endpoint it was, its last result, and a link back to Postback Deliveries. An endpoint that silently rots stops crediting your users without either of us noticing, so this is how we make sure you find out.

Postbacks vs. webhooks

The two channels do different jobs. Postbacks credit users: a URL template with macros, the industry-standard rewarded channel. Webhooks are for reversals, reconciliation, and automation: signed JSON events, the Stripe/GitHub model.

Verify a webhook by recomputing the HMAC over timestamp + "." + rawBody with your signing secret and comparing in constant time:

const crypto = require("crypto");

// Mount with the RAW body so bytes match what we signed:
//   app.post("/webhooks", express.raw({ type: "application/json" }), handler)
function verifyLootHQWebhook(req, secret) {
  const sig = req.get("x-loothq-signature") || "";   // "sha256=<hex>"
  const ts  = req.get("x-loothq-timestamp") || "";
  const raw = req.body.toString("utf8");             // the raw bytes, not re-stringified JSON

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(ts + "." + raw)
    .digest("hex");

  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;

  // Reject stale deliveries (replay protection): 5-minute window.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  return true;
}