Skip to content

Performance integration guide

Connect your server or affiliate tracker to CryptoAd Network Performance campaigns via HMAC-signed POST /v1/events or HTTPS GET /v1/postback URLs.

Updated

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 to clk_... on live traffic or tclk_... on sandbox checks.
  • {promoter} expands to the anonymous promoter token (prm_...), or direct for 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 with key_id=bpk_...).
  • Query HMAC: Pass key_id, ts, nonce and sig computed over GET\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}&currency=USD
Query parameterRequirement and format
event_idRequired unique ASCII identifier, 1 to 128 characters
eventRequired event slug, lowercase letters, digits and underscores
click_idRequired on first participant binding; clk_ or tclk_ prefix
customer_idRequired on first participant binding; opaque non-PII ID
offer_idOptional off_ identifier when running multiple offers
amountOptional exact USD decimal string, alias amount_usd
occurred_atOptional UTC RFC 3339 timestamp or 10-digit Unix seconds
properties_jsonOptional 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:

DispositionMeaning
acceptedLive event recorded and evaluated against offer rules
sandbox_matchedTest click event evaluated in dry-run mode at $0.00 cost
dropped_invalid_clickUnknown click ID or filtered traffic source
dropped_outside_windowClick or goal window expired before the event
dropped_unattributedCustomer ID has no prior click binding on this offer
dropped_duplicate_customerCustomer already bound to another click on this offer
dropped_late_eventEvent 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.