Postbacks

A postback is an HTTP GET from us to your server, sent when a user completes a survey, is screened out, or when a completion is taken back. It is how your users get their rewards.

Your URL

Set it per app. Use placeholders for the values you want; we replace them (URL-encoded):

https://your-server.example/yetipoll?user={user_id}&tx={transaction_id}&reward={reward}&status={status}&test={test}&sig={signature}

A URL without any placeholder gets all values appended as query parameters with the names below.

The URL has to start with http:// or https://, point to a public address of your own, and must not name a port: we call the standard port of the scheme and no other.

PlaceholderValue
{user_id}Your own id for the user
{transaction_id}Our id for the completion. A reversal reuses it
{reward}Amount in your currency. Negative on a reversal
{payout_usd}What the completion earned you, in US dollars
{currency}The name of your reward currency
{status}completed, screenout or reversed
{type}complete, screenout or bonus
{country}Two-letter country of the user, when known
{test}1 for sandbox and test postbacks, otherwise 0
{timestamp}Unix time the postback was built
{signature}HMAC-SHA256 of user_id:transaction_id:reward:status

What to do with one

  1. Verify the signature. Reject anything that does not match.
  2. Check test. 1 means sandbox or a test from the dashboard: run your code, credit nobody real.
  3. Apply it once. Store transaction_id together with status. If you have already handled that pair, do nothing.
  4. Answer with a 2xx status. The status code is all we look at and all we keep. What your server writes into the answer is neither stored nor shown, so use the status code to say what happened: 2xx for handled, anything else to be asked again.

The three statuses

statusMeaningreward
completedThe user finished a survey. Credit them.Positive
screenoutThe user did not qualify. Usually nothing to credit.0, or a small consolation amount
reversedAn earlier completion was taken back after a quality check. Deduct it.Negative: the original amount, negated

A reversal carries the same transaction_id as the completion it cancels. That is why you dedupe on the id and the status: the id alone would make you ignore every reversal.

Verifying the signature

signature = HMAC-SHA256("user_id:transaction_id:reward:status", secret key), lowercase hex. Use the values exactly as they arrive, and the secret key of the mode the postback belongs to (sandbox key when test=1 came from the sandbox).

<?php
// PHP
$secret   = getenv("YETIPOLL_SECRET");   // yp_live_sk_... or yp_test_sk_...
$payload  = $_GET["user"] . ":" . $_GET["tx"] . ":" . $_GET["reward"] . ":" . $_GET["status"];
$expected = hash_hmac("sha256", $payload, $secret);

if (!hash_equals($expected, $_GET["sig"] ?? "")) {
    http_response_code(403);
    exit;
}

if (alreadyHandled($_GET["tx"], $_GET["status"])) {   // your own lookup
    http_response_code(200);
    exit;
}

if (($_GET["test"] ?? "0") !== "1") {
    addToBalance($_GET["user"], (float) $_GET["reward"]);   // negative on a reversal
}
remember($_GET["tx"], $_GET["status"]);
http_response_code(200);
// Node.js (Express)
const crypto = require("crypto");

app.get("/yetipoll", async (req, res) => {
  const { user, tx, reward, status, test, sig = "" } = req.query;
  const expected = crypto
    .createHmac("sha256", process.env.YETIPOLL_SECRET)
    .update(`${user}:${tx}:${reward}:${status}`)
    .digest("hex");

  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.sendStatus(403);

  if (await alreadyHandled(tx, status)) return res.sendStatus(200);
  if (test !== "1") await addToBalance(user, Number(reward));
  await remember(tx, status);
  res.sendStatus(200);
});
# Python (Flask)
import hashlib, hmac, os
from flask import request

@app.get("/yetipoll")
def yetipoll():
    q = request.args
    payload = f"{q['user']}:{q['tx']}:{q['reward']}:{q['status']}"
    expected = hmac.new(os.environ["YETIPOLL_SECRET"].encode(), payload.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, q.get("sig", "")):
        return "", 403
    if already_handled(q["tx"], q["status"]):
        return "", 200
    if q.get("test", "0") != "1":
        add_to_balance(q["user"], float(q["reward"]))
    remember(q["tx"], q["status"])
    return "", 200

Retries

If your server does not answer with a 2xx status within a few seconds, we try again with growing pauses, from about a minute up to a day, for several attempts. Then the postback is marked failed. You can resend any undelivered postback from the postback log in your dashboard.

Testing

The app page in your dashboard has "Send a test completion" and "Send a test reversal". Both are signed with the secret key of the mode you are viewing and carry test=1. For an end-to-end test use the sandbox.

Reconciling

To double-check a postback, or to catch up after downtime, read the same data from the API: GET /api/v1/conversions.