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.
| Placeholder | Value |
|---|---|
{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
- Verify the signature. Reject anything that does not match.
- Check
test.1means sandbox or a test from the dashboard: run your code, credit nobody real. - Apply it once. Store
transaction_idtogether withstatus. If you have already handled that pair, do nothing. - 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
status | Meaning | reward |
|---|---|---|
completed | The user finished a survey. Credit them. | Positive |
screenout | The user did not qualify. Usually nothing to credit. | 0, or a small consolation amount |
reversed | An 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.