Postback lab: a recorded run and a signer
postback-tester sends signed test postbacks to a reward endpoint and checks what a single test postback cannot show: the retry that credits again, the reversal that is ignored, the forged request that is accepted. When this page was built, the example server of the repository ran once with a correct handler and once with a naive one, and the tool ran all 10 checks against each. The results below are the recorded ones.
- Checks
- 10, each run on both handlers
- Correct handler
- 10 of 10 passed, exit code 0
- Naive handler
- 8 of 10 failed, exit code 1
- Signer presets
- moonetix and custom, 5 README examples
- Run recorded
- 2026-11-16, version 1.1.0 on Node v22.23.4
- Commit
- f82a08d
Loading the recorded run
Recorded run
The same command ran against both handlers. Nothing here is typed in by hand: every status, time and balance is what the tool reported. Open a check to see what it guards against and the requests it sent.
Loading the recorded run
What a passing endpoint does
- Verify the signature first, with a constant-time comparison, before anything else runs.
- Store each transaction ID once, enforced by a unique key in the database, not by a lookup followed by an insert.
- On a reversal, take back what that transaction credited, once. Remember a reversal for an unknown transaction so a late credit is not paid.
- Answer 2xx for repeats. A 4xx or 5xx makes the network retry a postback you already processed.
- Answer only after the change is committed, and within a few seconds.
Both handlers are in examples/echo-server.js. The balance column works because the server exposes the balance of the test user, which is how the tool tells a duplicate credit from a correct one when both answer 200. Handlers in PHP, Node.js, Python and Java that pass every check: offerwall-postback-handlers.
Signer
Paste the postback URL you gave the network and a test key to get the signed request the tool would send, the exact string that was signed, and curl commands for a credit, its retry and its reversal. The page runs the same code as the command line tool, in this tab. Nothing is sent anywhere.
The credit
- Signed string
-- Signature
-- Signed URL
-
Send it with curl
Run the three in this order against staging, and read the balance of the test user after each.
-
-
-
-
Or let the tool run all 10 checks
The same settings as a command. It needs Node.js 22 and nothing else.
-
Point it at staging, never at production: the checks credit and reverse real balances.
Run it
The commands below are the ones in the README. The exit code is 0 when every check passes and 1 when one fails, so the same line works in a terminal and in CI.
export MOONETIX_POSTBACK_KEY=... # Postback page of your Moonetix dashboard
npx @moonetix/postback-tester --preset moonetix \
'https://staging.example.com/postback?user={user_id}&tx={transaction_id}&event={event_id}&status={status}&reward={reward}&payout={payout}&hash={hash}'
The moonetix preset reproduces a Moonetix postback byte for byte: the documented macros, values encoded like PHP rawurlencode(), and {hash} as lowercase hex HMAC-SHA256 of transaction_id:user_id:reward:status.
POSTBACK_SECRET=... npx @moonetix/postback-tester \
'https://staging.example.com/cb?uid=[USER_ID]&amount=[AMOUNT]&oid=[TX]&status=[STATUS]&sig=[SIGNATURE]' \
--set amount={reward} --set tx={transaction_id} \
--sign md5 --sign-input '[USER_ID][AMOUNT][TX][SECRET]' \
--credit-status approved --reversal-status rejected \
--ok-body '^1$'POSTBACK_SECRET=... npx @moonetix/postback-tester \
'https://staging.example.com/pb?user={user_id}&tx={transaction_id}&amount={reward}&status={status}&signature={signature}' \
--sign hmac-sha256 --sign-input '{user_id}{transaction_id}{reward}{status}' \
--reversal-status 2 --reversal-reward negativePOSTBACK_SECRET=... npx @moonetix/postback-tester \
'https://staging.example.com/webhooks/rewards' \
--method POST --body-type json \
--body '{"user":"{user_id}","tx":"{transaction_id}","status":{status},"reward":{reward}}' \
--sign hmac-sha1 --sign-input '{body}' --sign-encoding base64 --sign-header X-SignaturePOSTBACK_SECRET=... npx @moonetix/postback-tester \
'https://staging.example.com/pb?key={secret}&user={user_id}&tx={transaction_id}&reward={reward}&status={status}'The secret is read from POSTBACK_SECRET. It is never accepted on the command line or in a config file, and reports show it as [secret].
name: Postback
on: [deployment_status]
jobs:
postback:
if: github.event.deployment_status.state == 'success'
runs-on: ubuntu-latest
steps:
- uses: moonetix/postback-tester@v1
with:
preset: moonetix
url: https://staging.example.com/postback?user={user_id}&tx={transaction_id}&status={status}&reward={reward}&hash={hash}
args: --balance-url https://staging.example.com/test/balance?user={user_id} --balance-path balance
secret: ${{ secrets.STAGING_POSTBACK_KEY }}
npx @moonetix/postback-tester --config postback-tester.json --json > postback-report.json
The step fails when a check fails, and the report is written to the job summary.
git clone https://github.com/moonetix/postback-tester.git
cd postback-tester
export MOONETIX_POSTBACK_KEY=test_postback_key_not_secret
node examples/echo-server.js > echo-server.log & # correct handler on 127.0.0.1:8080
node bin/postback-tester.js --preset moonetix \
'http://127.0.0.1:8080/postback?user={user_id}&tx={transaction_id}&status={status}&reward={reward}&hash={hash}' \
--balance-url 'http://127.0.0.1:8080/balance?user={user_id}' --balance-path balance
Stop the server, start it again with MODE=naive and run the same command to get the 8 failures shown above.
Maintained by Moonetix, an affiliate network.