Performance campaigns verify conversions and revenue-share accruals from server-to-server events sent by your backend or affiliate tracker. You can send batches over signed JSON (POST /v1/events) or fire single-event HTTPS postback URLs (GET /v1/postback).
Both transports share the same idempotency store, attribution rules and rule engine, and both support zero-cost sandbox verification before your campaign goes live.
Outbound landing macros
When a participant opens your offer, macros in the path or query string of your https:// landing page template are expanded before redirect:
{click_id}expands toclk_...on live traffic ortclk_...on sandbox checks.{promoter}expands to the anonymous promoter token (prm_...), ordirectfor personal participation.{offer}expands to your offer identifier (off_...).{label}expands to an optional sanitized promoter sub-tag.
Persist click_id alongside your internal opaque customer_id when the user signs up or starts a session. Note that {promoter} is an outbound landing macro for your own analytics only; never send promoter tokens on inbound events, and never send email addresses or personal data as customer_id.
Attribution binding and monetary formatting
On the first event that binds a participant to an offer, you must include both click_id and customer_id. On subsequent events for that same customer, send customer_id (with optional click_id or offer_id).
Monetary amounts (amount_usd in JSON, or amount on GET postback) must be base-10 USD strings with up to 8 fractional digits, bounded to 10000000.00000000 per event. JSON floating-point numbers are rejected. Negative decimal strings are accepted only on revenue-share events when player winnings or chargebacks make daily net revenue negative. Event timestamps (occurred_at) use UTC RFC 3339 or 10-digit Unix seconds and must not be older than 72 hours. Every event is idempotent per (advertiser_id, event_id).
Option 1: HMAC-signed JSON batch (POST /v1/events)
Send one event object or {"events": [...]} (up to 100 events, max 256 KiB) with four headers: X-Bounties-Key-Id (bpk_...), X-Bounties-Timestamp (UTC Unix seconds within 300 seconds), X-Bounties-Nonce (32 lowercase hex characters) and X-Bounties-Signature (64 lowercase hex characters).
Decode your 64-character hex signing secret into 32 raw bytes and compute HMAC-SHA256 over the newline-joined canonical string POST\n/v1/events\n{timestamp}\n{nonce}\n{sha256_hex(raw_body)}:
BOUNTIES_EVENT_URL='https://events.aflk.io'
BODY='{"event_id":"test_evt_001","click_id":"tclk_01jc900sandbox","customer_id":"sandbox_user_1","event":"signup"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -r | awk '{print $1}')
SIG=$(printf 'POST\n/v1/events\n%s\n%s\n%s' "$TS" "$NONCE" "$HASH" \
| openssl dgst -sha256 -mac HMAC -macopt "hexkey:$BOUNTIES_SECRET_HEX" -r | awk '{print $1}')
curl -sS -X POST "$BOUNTIES_EVENT_URL/v1/events" \
-H "Content-Type: application/json" \
-H "X-Bounties-Key-Id: $BOUNTIES_KEY_ID" \
-H "X-Bounties-Timestamp: $TS" \
-H "X-Bounties-Nonce: $NONCE" \
-H "X-Bounties-Signature: $SIG" \
-d "$BODY"
Node.js
import { createHash, createHmac, randomBytes } from "node:crypto";
export async function sendEvents({ baseUrl, keyId, secretHex, events }) {
const rawBody = JSON.stringify({ events });
const ts = String(Math.floor(Date.now() / 1000));
const nonce = randomBytes(16).toString("hex");
const bodyHash = createHash("sha256").update(rawBody).digest("hex");
const canonical = ["POST", "/v1/events", ts, nonce, bodyHash].join("\n");
const sig = createHmac("sha256", Buffer.from(secretHex, "hex"))
.update(canonical)
.digest("hex");
const res = await fetch(`${baseUrl}/v1/events`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Bounties-Key-Id": keyId,
"X-Bounties-Timestamp": ts,
"X-Bounties-Nonce": nonce,
"X-Bounties-Signature": sig,
},
body: rawBody,
});
return res.json();
}
Python
import hashlib, hmac, json, os, time, urllib.request
def send_events(base_url: str, key_id: str, secret_hex: str, events: list[dict]) -> dict:
raw = json.dumps({"events": events}, separators=(",", ":")).encode("utf-8")
ts = str(int(time.time()))
nonce = os.urandom(16).hex()
body_hash = hashlib.sha256(raw).hexdigest()
canonical = f"POST\n/v1/events\n{ts}\n{nonce}\n{body_hash}".encode("utf-8")
sig = hmac.new(bytes.fromhex(secret_hex), canonical, hashlib.sha256).hexdigest()
req = urllib.request.Request(
f"{base_url}/v1/events",
data=raw,
method="POST",
headers={
"Content-Type": "application/json",
"X-Bounties-Key-Id": key_id,
"X-Bounties-Timestamp": ts,
"X-Bounties-Nonce": nonce,
"X-Bounties-Signature": sig,
},
)
with urllib.request.urlopen(req, timeout=10) as resp:
return json.loads(resp.read().decode("utf-8"))
Go
package bountiesclient
import (
"bytes"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"fmt"
"net/http"
"strconv"
"time"
)
func SignAndPost(baseURL, keyID, secretHex string, rawBody []byte) (*http.Response, error) {
secret, err := hex.DecodeString(secretHex)
if err != nil {
return nil, err
}
nonceBytes := make([]byte, 16)
if _, err := rand.Read(nonceBytes); err != nil {
return nil, err
}
ts := strconv.FormatInt(time.Now().Unix(), 10)
nonce := hex.EncodeToString(nonceBytes)
sum := sha256.Sum256(rawBody)
canonical := fmt.Sprintf("POST\n/v1/events\n%s\n%s\n%x", ts, nonce, sum)
mac := hmac.New(sha256.New, secret)
mac.Write([]byte(canonical))
sig := hex.EncodeToString(mac.Sum(nil))
req, err := http.NewRequest(http.MethodPost, baseURL+"/v1/events", bytes.NewReader(rawBody))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Bounties-Key-Id", keyID)
req.Header.Set("X-Bounties-Timestamp", ts)
req.Header.Set("X-Bounties-Nonce", nonce)
req.Header.Set("X-Bounties-Signature", sig)
return http.DefaultClient.Do(req)
}
PHP
<?php
function send_bounties_events(string $baseUrl, string $keyId, string $secretHex, array $events): array {
$raw = json_encode(['events' => $events], JSON_UNESCAPED_SLASHES);
$ts = (string) time();
$nonce = bin2hex(random_bytes(16));
$bodyHash = hash('sha256', $raw);
$canonical = "POST\n/v1/events\n{$ts}\n{$nonce}\n{$bodyHash}";
$sig = hash_hmac('sha256', $canonical, hex2bin($secretHex));
$ch = curl_init("{$baseUrl}/v1/events");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $raw,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
"X-Bounties-Key-Id: {$keyId}",
"X-Bounties-Timestamp: {$ts}",
"X-Bounties-Nonce: {$nonce}",
"X-Bounties-Signature: {$sig}",
],
]);
$resp = curl_exec($ch);
curl_close($ch);
return json_decode((string) $resp, true) ?? [];
}
Option 2: HTTPS GET postback (/v1/postback)
Affiliate trackers and mobile measurement partners can call GET /v1/postback over HTTPS. Plain http:// requests and duplicate query parameter names are rejected with 400, and query secrets (token, sig) are scrubbed from access logs before storage.
Choose one authentication mode per URL (sending both token and sig returns 400 ambiguous_auth_mode):
- Postback secret token: Pass
token=advpb_<64hex>(optionally withkey_id=bpk_...). - Query HMAC: Pass
key_id,ts,nonceandsigcomputed overGET\n/v1/postback\n{ts}\n{nonce}\n{sorted_rfc3986_query_without_sig}.
https://events.aflk.io/v1/postback?token=advpb_YOUR_64_HEX_TOKEN&click_id={click_id}&customer_id={customer_id}&event=deposit&event_id={event_id}&amount={amount}¤cy=USD
| Query parameter | Requirement and format |
|---|---|
| event_id | Required unique ASCII identifier, 1 to 128 characters |
| event | Required event slug, lowercase letters, digits and underscores |
| click_id | Required on first participant binding; clk_ or tclk_ prefix |
| customer_id | Required on first participant binding; opaque non-PII ID |
| offer_id | Optional off_ identifier when running multiple offers |
| amount | Optional exact USD decimal string, alias amount_usd |
| occurred_at | Optional UTC RFC 3339 timestamp or 10-digit Unix seconds |
| properties_json | Optional URL-encoded flat scalar JSON object, or use prop_ keys |
Dispositions and drop reasons
Every processed event returns a structured result so you can inspect delivery in your integration console:
| Disposition | Meaning |
|---|---|
| accepted | Live event recorded and evaluated against offer rules |
| sandbox_matched | Test click event evaluated in dry-run mode at $0.00 cost |
| dropped_invalid_click | Unknown click ID or filtered traffic source |
| dropped_outside_window | Click or goal window expired before the event |
| dropped_unattributed | Customer ID has no prior click binding on this offer |
| dropped_duplicate_customer | Customer already bound to another click on this offer |
| dropped_late_event | Event timestamp is older than 72 hours |
Sandbox verification before launch
Before submitting a Performance campaign, mint a sandbox click (tclk_...) in the composer or the integration console and fire one real authenticated event. When the engine records sandbox_matched, submission unlocks immediately with zero charge.