The RevRake API.

Base URLs

The API is four signed endpoints for the operator's platform, two to write and two to read, and the tracking link that visitors open. The signed endpoints are also published as an OpenAPI 3.1 file.

The portals at app.revrake.com use their own endpoints behind a signed-in session. They are not a public API and may change without notice. Reports, the ledger and payout rows can also be downloaded there as CSV.

Keys

There are two kinds of key. Each has a key ID and a secret, and each signs requests the same way. Keys are never shared: every party has its own.

• A new key revokes the old one at once, for both kinds. An affiliate can also revoke their key and have none.
• An affiliate key works only while the affiliate is approved in the program. Otherwise a read answers 403 affiliate_inactive.
• With an affiliate key, the affiliate parameter is ignored and by=affiliate is answered by day.
• The rate limit of reads is counted per key.

Authentication

Every /v1 request is signed with a key. Every request carries three headers:

To sign a request:

1. Build the body and keep the exact bytes you will send.
2. Take the current Unix time in seconds, as decimal text.
3. Concatenate the timestamp, a dot (.) and the body.
4. Compute HMAC-SHA256 of that under your secret and write it as lower-case hex.
5. Send the body unchanged, with the three headers.

Signing a read

A GET has no body, so the signature covers the request target instead: the path and the query exactly as sent, for example 1790000000./v1/reports?by=link&days=7. With no query, it is the timestamp, a dot and the path. Build the address once, sign that text and send that text: a client that re-orders or re-encodes the query after signing breaks the signature.

• The key is checked first, then the timestamp, then the signature.
• A Content-Type header is not required. Send application/json for events and text/csv for files.
• A rotated key stops working at once.

Signing samples

Each sample has one signing function, sends a registration and then reads a report. Replace the key ID and the secret with yours.

KEY="pb_your_key_id"
SECRET="your_secret"
BASE="https://app.revrake.com"

# sign <payload>: hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
sign() { printf '%s.%s' "$TS" "$1" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //'; }

# Write: the payload is the body.
TS=$(date +%s)
BODY='{"type":"registration","player_id":"PLR-1001","click_id":"CID_FROM_LANDING_URL"}'
curl -X POST "$BASE/v1/postback" \
  -H "Content-Type: application/json" \
  -H "X-RevRake-Key: $KEY" \
  -H "X-RevRake-Timestamp: $TS" \
  -H "X-RevRake-Signature: $(sign "$BODY")" \
  -d "$BODY"

# Read: the payload is the path and the query, exactly as sent.
TS=$(date +%s)
TARGET='/v1/reports?by=link&days=7'
curl "$BASE$TARGET" \
  -H "X-RevRake-Key: $KEY" \
  -H "X-RevRake-Timestamp: $TS" \
  -H "X-RevRake-Signature: $(sign "$TARGET")"

import { createHmac } from 'node:crypto';

const KEY = 'pb_your_key_id';
const SECRET = 'your_secret';
const BASE = 'https://app.revrake.com';

// hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
function sign(secret, timestamp, payload) {
  return createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex');
}

function headers(payload) {
  const ts = Math.floor(Date.now() / 1000).toString();
  return { 'X-RevRake-Key': KEY, 'X-RevRake-Timestamp': ts, 'X-RevRake-Signature': sign(SECRET, ts, payload) };
}

// Write: the payload is the body. Send the same string you signed.
const body = JSON.stringify({ type: 'registration', player_id: 'PLR-1001', click_id: 'CID_FROM_LANDING_URL' });
const write = await fetch(`${BASE}/v1/postback`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', ...headers(body) },
  body,
});
console.log(write.status, await write.json());

// Read: the payload is the path and the query, exactly as sent.
const target = '/v1/reports?by=link&days=7';
const read = await fetch(BASE + target, { headers: headers(target) });
console.log(read.status, await read.json());

import hashlib
import hmac
import json
import time
import urllib.error
import urllib.request

KEY = "pb_your_key_id"
SECRET = "your_secret"
BASE = "https://app.revrake.com"


def sign(secret: str, timestamp: str, payload: bytes) -> str:
    """hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret"""
    return hmac.new(secret.encode(), timestamp.encode() + b"." + payload, hashlib.sha256).hexdigest()


def call(method: str, target: str, body: bytes | None = None):
    ts = str(int(time.time()))
    # Write: the payload is the body. Read: the path and the query, as sent.
    payload = body if body is not None else target.encode()
    headers = {"X-RevRake-Key": KEY, "X-RevRake-Timestamp": ts, "X-RevRake-Signature": sign(SECRET, ts, payload)}
    if body is not None:
        headers["Content-Type"] = "application/json"
    req = urllib.request.Request(BASE + target, data=body, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=10) as res:
            return res.status, json.load(res)
    except urllib.error.HTTPError as e:
        return e.code, json.load(e)


event = {"type": "registration", "player_id": "PLR-1001", "click_id": "CID_FROM_LANDING_URL"}
print(*call("POST", "/v1/postback", json.dumps(event).encode()))
print(*call("GET", "/v1/reports?by=link&days=7"))

<?php
const KEY = 'pb_your_key_id';
const SECRET = 'your_secret';
const BASE = 'https://app.revrake.com';

// hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret
function sign(string $secret, string $timestamp, string $payload): string
{
    return hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
}

function call(string $method, string $target, ?string $body = null): array
{
    $ts = (string) time();
    // Write: the payload is the body. Read: the path and the query, as sent.
    $payload = $body ?? $target;
    $headers = [
        'X-RevRake-Key: ' . KEY,
        'X-RevRake-Timestamp: ' . $ts,
        'X-RevRake-Signature: ' . sign(SECRET, $ts, $payload),
    ];
    $ch = curl_init(BASE . $target);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10]);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $answer = curl_exec($ch);
    return [curl_getinfo($ch, CURLINFO_RESPONSE_CODE), json_decode($answer, true)];
}

$event = ['type' => 'registration', 'player_id' => 'PLR-1001', 'click_id' => 'CID_FROM_LANDING_URL'];
print_r(call('POST', '/v1/postback', json_encode($event)));
print_r(call('GET', '/v1/reports?by=link&days=7'));

package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
	"strconv"
	"time"
)

const (
	key    = "pb_your_key_id"
	secret = "your_secret"
	base   = "https://app.revrake.com"
)

// sign is the hex HMAC-SHA256 of "<timestamp>.<payload>" under the secret.
func sign(secret, timestamp string, payload []byte) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(payload)
	return hex.EncodeToString(mac.Sum(nil))
}

func call(method, target string, body []byte) (int, string, error) {
	ts := strconv.FormatInt(time.Now().Unix(), 10)
	// Write: the payload is the body. Read: the path and the query, as sent.
	payload := body
	if body == nil {
		payload = []byte(target)
	}
	req, err := http.NewRequest(method, base+target, bytes.NewReader(body))
	if err != nil {
		return 0, "", err
	}
	req.Header.Set("X-RevRake-Key", key)
	req.Header.Set("X-RevRake-Timestamp", ts)
	req.Header.Set("X-RevRake-Signature", sign(secret, ts, payload))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	res, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
	if err != nil {
		return 0, "", err
	}
	defer res.Body.Close()
	answer, err := io.ReadAll(res.Body)
	return res.StatusCode, string(answer), err
}

func main() {
	event := []byte(`{"type":"registration","player_id":"PLR-1001","click_id":"CID_FROM_LANDING_URL"}`)
	fmt.Println(call("POST", "/v1/postback", event))
	fmt.Println(call("GET", "/v1/reports?by=link&days=7", nil))
}

Test vector

With these inputs your code must produce exactly these signatures:

Secret

test_secret

Timestamp

1791072000

Body

{"type":"registration","player_id":"PLR-1001","btag":"1001_1"}

Signature

115d8c73c6069d8953a36ca3a68c114da6232e4ba31889fd519d41ab1350a603

Request target of a read

/v1/reports?by=link&days=7

Signature of the read

ed1ed72dd7ddef22c762f63b8919011e7c36c7214b55b72693c5927fb4b911d0

Limits

These are all the limits the product applies to integrations, tracking and affiliates today, with their numbers. Sign-in, password reset and applications also have limits against abuse.

The two write endpoints, POST /v1/postback and POST /v1/files, are limited per key (see the table). Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; a refusal is 429 with Retry-After. Send at the pace of your events, and use batches for a backfill. The tracking link has no rate limit; an unusual burst of clicks on one link from one address raises a fraud flag and is still redirected.

The rate limit of reads

• Each key may make 120 reads a minute. The allowance is a bucket of 120: a read takes one, and one comes back every half second. A key that has been idle can make 120 reads at once; after that, two a second.
• Every read answer carries X-RateLimit-Limit (always 120) and X-RateLimit-Remaining (how many reads are left right now).
• Past the limit the answer is 429 rate_limited with a Retry-After header: the seconds to wait. Wait, then send the same request again, signed with a fresh timestamp.
• The limit is counted per key: the operator's key and each affiliate's key have their own allowance.

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 1

{"error":"rate_limited","message":"Too many requests: at most 120 reads a minute per key. One more is allowed every half second; wait the seconds in Retry-After and try again."}

Handling a 429

// read(target) signs one GET with a fresh timestamp and sends it,
// as in the signing samples.
async function readWithRetry(target, tries = 5) {
  for (let i = 0; i < tries; i++) {
    const res = await read(target);
    if (res.status !== 429) return res;
    const seconds = Number(res.headers.get('Retry-After')) || 1;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
  throw new Error('still rate limited after ' + tries + ' tries');
}

POST /v1/postback

Reports one event from the operator's platform. The body is a JSON object with a type and the fields of that type, or a JSON array of such objects (a batch).

POST https://app.revrake.com/v1/postback

• type is one of registration, deposit, chargeback, ngr.
• A field that is not listed for the type is refused with 422, so a typo is never silently ignored.
• ts is the time of the event in RFC 3339 form (2026-10-04T08:15:00Z). When it is left out, the time of the request is used. It must carry a UTC offset (Z or +03:00); a time without one is refused. It may not be more than a day in the future.
• An amount is a decimal, as JSON text or a JSON number: "25.00" or 25.5. No thousands separator, no exponent, and no more decimals than the currency has.
• currency is a three-letter ISO 4217 code. Lower case is accepted. When it is left out, the workspace's reporting currency is used.
• Text values are trimmed of spaces at both ends, except click_id and btag: send them exactly as they arrived on the landing page.

registration

A new player. Send click_id, btag, promo_code, or several of them; with none, the player is recorded as not attributed. The player is attributed once, here. Answer: attribution.

{"type":"registration","player_id":"PLR-1001","click_id":"01K6QF3M8Z5T7W9XB2C4D6E8GH","btag":"1001_1"}

{
  "status": "accepted",
  "event_type": "registration",
  "event_id": "0199b2c4-6f1e-7a53-9d0c-2b8f4e1a7c33",
  "attribution": {
    "attributed": true,
    "reason": "click",
    "affiliate_number": 1001,
    "link_number": 1,
    "click_id": "01K6QF3M8Z5T7W9XB2C4D6E8GH",
    "policy_version": 1,
    "window_days": 30,
    "model": "last_click"
  }
}

deposit

Send a deposit event for each deposit, with your transaction ID in txn_id. The deal chooses whether CPA requires the first deposit or cumulative deposits, net of chargebacks, to reach its minimum. Qualification creates one CPA commission per player, on hold.

{"type":"deposit","player_id":"PLR-1001","txn_id":"TX-88213","amount":"25.00","currency":"KES","first":true}

{
  "status": "accepted",
  "event_type": "deposit",
  "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "commission": {
    "effect": "created",
    "type": "cpa",
    "amount_minor": 4000,
    "status": "hold"
  }
}

chargeback

Send a chargeback event with its own txn_id and the original deposit’s txn_id in ref_txn_id. It reverses that whole deposit. For cumulative CPA, the commission is taken back only if the remaining qualifying total falls below the minimum: a held commission is cancelled; an approved or paid one gets a reversal row.

{"type":"chargeback","txn_id":"CB-5001","ref_txn_id":"TX-88213"}

{
  "status": "accepted",
  "event_type": "chargeback",
  "event_id": "0199cc10-7b2d-7c41-a3f0-5d2e8b9c1f47",
  "commission": {
    "effect": "cancelled",
    "type": "cpa",
    "amount_minor": 4000,
    "status": "rejected"
  }
}

ngr

The net gaming revenue of a player for a day or a month. It earns the revenue share of the deal version in effect at the end of the period, on hold. The player must be registered. Answer: commission.

{"type":"ngr","player_id":"PLR-1001","period":"2026-10-03","amount":"118.40","currency":"KES"}

{
  "status": "accepted",
  "event_type": "ngr",
  "event_id": "0199b2d1-5c0e-7b42-8a17-3e9d6f0c4b21",
  "commission": {
    "effect": "created",
    "type": "revshare",
    "amount_minor": 2960,
    "status": "hold"
  }
}

The answer

An event that was stored, or was already stored, is answered with 200 and a JSON object. Fields that do not apply are left out.

{
  "status": "accepted",
  "event_type": "deposit",
  "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "waiting_for_player": true
}

{
  "status": "duplicate",
  "event_type": "deposit",
  "event_id": "0199b31f-8c02-7a66-b4e1-2d7f9a3c6e15",
  "duplicate_of": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
  "detail": "The same deposit (TX-88213) was already reported through the API; this one adds nothing."
}

{
  "status": "duplicate",
  "event_type": "deposit",
  "event_id": "0199b2ca-11d4-7f09-8c55-0a6e2d4b7f90",
  "commission": { "effect": "none", "reason": "not_first" }
}

A commission is created with status hold. It is approved automatically when the hold period of the deal ends, unless something still holds it: an open fraud flag, an affiliate who is not approved, or a missing exchange rate.

Attribution reasons

The click ID is tried first. If it is not one of yours, the btag is tried. When the policy says the btag wins and the btag matches a link, the btag is tried first instead. A btag that matches a link attributes the player even when no click is found. A promo code is tried last, only when neither the click ID nor the btag attributed the player. The policy, its window and which of the two wins are set on the Integration page; each change is a new version. When the policy says the promo code wins, a code that matches a link is tried before both, and one that does not falls back to them. A deal may set its own window, which replaces the policy's for clicks on its affiliates' links.

Why no commission was created

Batches

The body may be a JSON array of 1 to 1,000 events, sent to the same endpoint with the same headers. The signature covers the whole array. Events are handled in order, each on its own, so one refused event never stops the rest.

A batch that could be read is answered with 200, also when every event in it was refused. Look at the counts.

[
  {"type":"deposit","player_id":"PLR-1001","txn_id":"TX-88213","amount":"25.00","first":true},
  {"type":"ngr","player_id":"PLR-1001","period":"2026-10-03","amount":"118.40"},
  {"type":"ngr","player_id":"PLR-1002","period":"October","amount":"-12.50"}
]

{
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "event_type": "deposit",
      "event_id": "0199b2c9-03aa-7e10-b6d2-91c07f5e2a18",
      "commission": { "effect": "created", "type": "cpa", "amount_minor": 4000, "status": "hold" }
    },
    {
      "index": 1,
      "status": "duplicate",
      "event_type": "ngr",
      "event_id": "0199b2d1-5c0e-7b42-8a17-3e9d6f0c4b21",
      "commission": { "effect": "created", "type": "revshare", "amount_minor": 2960, "status": "hold" }
    },
    {
      "index": 2,
      "status": "rejected",
      "field": "period",
      "message": "period must be a day (2026-10-03) or a month (2026-10), not in the future."
    }
  ],
  "accepted": 1,
  "duplicate": 1,
  "rejected": 1
}

POST /v1/files

Pushes a daily CSV file, as an alternative to uploading it on the Integration page or letting RevRake fetch it from an address your platform publishes it at. The body is the file itself; the headers and the signature are those of an event, and the signature covers the timestamp and the file. The file name goes in the filename query parameter; it is shown in the portal and is otherwise not used.

POST https://app.revrake.com/v1/files?filename=sales-2026-10-03.csv

The header row decides which file it is: a file with a registration_date column is a REG file, one with an activitydate column is a SALES file. Column names are matched without regard to case. Columns that are not listed below may stay in the file; they are ignored.

Dates are read as YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, RFC 3339 or YYYY/MM/DD. Without a UTC offset, the file timezone in workspace Settings applies (UTC by default). A timestamp with an offset identifies an exact moment; for SALES, its calendar day in the file timezone is used. Day and month are never guessed: 30/09/2026 is refused.

REG file: one row per registered player

brand_name,registration_date,btag,promo_code,player_id,player_country
Example,2026-10-03,1001_1,,PLR-1001,KE
Example,2026-10-03,,,PLR-1002,KE
Example,2026-10-03,,GARAGE50,PLR-1003,KE

SALES file: one row per player per day

brand_name,activitydate,player_id,btag,currency,deposits,first_deposit_amount,chargeback,casino_net_revenue,sports_net_revenue
Example,2026-10-03,PLR-1001,1001_1,KES,3500.00,2500.00,0,118.40,0
Example,2026-10-03,PLR-1002,,KES,900.00,0,0,-12.50,

• Each SALES row records one daily money summary and, when revenue cells are filled, a separate NGR event. They are processed independently: a rejected monetary summary does not undo accepted revenue, or vice versa. Check every problem in the answer.
• One summary per brand, player and activity day; the first accepted currency is fixed. Identical monetary values replay even after renaming or reordering the file. Changing amounts, currency or the timezone boundaries of an accepted day is a conflict, including changes from zero. Previously recorded money stays unchanged.
• deposits, first_deposit_amount and chargeback are required columns. Empty cells mean zero. Amounts must be nonnegative decimals with the precision of the row’s currency. Confirm these definitions with your platform before connecting its export.
• Send REG before SALES. Money summaries received first are kept and priced when registration arrives. NGR for an unknown player is refused: after REG, resend SALES or NGR. The saved money summary replays.
• A summary covers individual postbacks for its activity day and currency in the file timezone, without adding their amounts twice. Transaction IDs remain addressable. Known deposits or chargebacks exceeding the summary, or inconsistent first-deposit evidence, are conflicts.
• For cumulative CPA, deposits minus chargebacks must reach the deal’s minimum. Each daily cashflow uses its activity date’s exchange rate; individual postbacks use their own UTC event day. Missing conversion rates hold settlement under fx_rate_missing. Missing chargeback rates block payment under chargeback_fx_missing until reconciliation, including commissions already claimed by a payout.
• For first-deposit CPA, an aggregate chargeback may not identify which deposit was reversed. An ambiguous money summary for a registered player is refused. If the summary arrived before REG, it is kept and registration succeeds, but the resulting held CPA waits under chargeback_reference_missing. For transaction-reference review, send a chargeback with ref_txn_id set to the original deposit’s transaction ID.
• Revenue is separate from immutable money totals: a changed daily NGR amount is a restatement, and its commission difference becomes an adjustment.

The answer

A readable file returns 200. Counts are per event, not just per row: a SALES row can record a money summary and NGR separately, including a partial success. Always check rejected and problems.

{
  "id": "0199b31e-2a40-7d18-9b6c-4f1e7a2c5d03",
  "filename": "sales-2026-10-03.csv",
  "kind": "sales",
  "uploaded_at": "2026-10-04T02:00:07Z",
  "rows_total": 2,
  "accepted": 3,
  "duplicates": 0,
  "rejected": 1,
  "skipped": 0,
  "problems": ["line 3: Player PLR-1002 is not registered. Send the registration first."]
}

GET /v1/reports

Answers the report of the Reports page: clicks, flagged clicks, registrations, first deposits and earnings, grouped one way, for the days up to today in the workspace's timezone. Today's figures are refreshed when a report is requested, at most every 30 seconds on a busy program.

GET https://app.revrake.com/v1/reports?by=link&days=7

{
  "by": "link",
  "from": "2026-09-28",
  "to": "2026-10-04",
  "currency": "KES",
  "rows": [
    {
      "key": "0199a7f0-41c2-7e55-b1d9-6c3a8e2f7b10",
      "label": "telegram-october",
      "clicks": 1840,
      "flagged_clicks": 212,
      "registrations": 96,
      "ftds": 31,
      "earnings_minor": 12400000
    }
  ],
  "total": {
    "key": "",
    "label": "",
    "clicks": 1840,
    "flagged_clicks": 212,
    "registrations": 96,
    "ftds": 31,
    "earnings_minor": 12400000
  }
}

As CSV

With format=csv the answer is a file. Its first column is named after the grouping and holds the label; then clicks, flagged_clicks, registrations, first_deposits and earnings_<currency> as a decimal. The last line is the total.

link,clicks,flagged_clicks,registrations,first_deposits,earnings_KES
telegram-october,1840,212,96,31,124000.00
total,1840,212,96,31,124000.00

GET /v1/commissions

Answers one page of the commission ledger, newest first unless you sort otherwise. Rows are never edited in their amounts and never deleted, but a row's status changes after it is written: hold, then approved, then paid, or rejected. A sync must read a period again and update rows by id, not only fetch new rows.

GET https://app.revrake.com/v1/commissions?from=2026-09-01&to=2026-10-01&per_page=500

{
  "currency": "KES",
  "totals": { "hold": 1240000, "approved": 3720000, "paid": 9800000 },
  "owed": { "KES": { "hold": 1240000, "approved": 3720000, "paid": 9800000 } },
  "period": true,
  "commissions": [
    {
      "id": "0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58",
      "occurred_at": "2026-09-14T08:20:00Z",
      "type": "cpa",
      "currency": "KES",
      "gross_currency": "KES",
      "reporting_minor": 400000,
      "affiliate_name": "Odds Garage",
      "affiliate_number": 1001,
      "player_ref": "PLR-1001",
      "deal_name": "CPA 4000",
      "deal_version": 2,
      "gross_minor": 250000,
      "rate_snapshot": 400000,
      "amount_minor": 400000,
      "status": "approved",
      "status_reason": "",
      "hold_until": "2026-10-14T08:20:00Z",
      "status_note": ""
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 500
}

A commission row

Program lists: affiliates, links, deals

Your backend can list the program as the portal shows it, signed like the other reads and counted in the same limit. GET /v1/affiliates and GET /v1/deals need the operator key; with an affiliate key they answer 403 operator_key_required. GET /v1/links answers the brand's links, or one affiliate's with affiliate=<number>; with an affiliate key, that affiliate's own links.

Lists are paged with page (from 1) and per_page (1 to 500, default 100) and carry total. GET /v1/affiliates also takes status: pending, approved, rejected or suspended. Creating affiliates or links through the API is not offered yet: tell us what you would use it for.

GET https://app.revrake.com/v1/links?affiliate=1001&per_page=100

Each affiliate

Each link

Each deal

Warehouse export

Set up on the Integration page: every night RevRake writes the previous day of each brand to your own bucket on any S3-compatible service, at <folder>/<brand>/<YYYY-MM-DD>/, the day counted in the workspace's timezone. Four gzipped CSV files (UTF-8, a header row, RFC 4180 quoting), then manifest.json. The manifest is written last: load a day once it exists, and check each file's rows, bytes and sha256 against it.

A row belongs to the day it arrived (a click: when it was clicked), so a daily file that comes late is in the day it came, never lost. Times are RFC 3339 in UTC with milliseconds; amounts are decimals in their currency. Statuses are as they were at the export: a commission's status changes later, so read GET /v1/commissions again for the current one. A failed day is retried every hour and caught up for up to seven days; exporting a day again overwrites its files. New columns may be added at the end of a file; schema_version in the manifest changes when a loader must change.

manifest.json: schema_version, workspace, brand, day, timezone, from and to (the day's bounds in UTC), generated_at, and files: for each, name, rows, bytes, sha256 (of the gzipped file).

clicks.csv.gz: every click on the brand's links that day, flagged ones included.

players.csv.gz: players whose registration arrived that day.

events.csv.gz: every accepted brand event that arrived that day, including daily SALES summaries, with its payload.

commissions.csv.gz: commission rows written that day.

Idempotency

Each event has a natural key. An identical retry returns the stored answer with "status":"duplicate". A deposit waiting for registration has its answer updated when registration arrives. Changed monetary facts can conflict; NGR restatements use revisions. After a timeout, retry with a fresh signature timestamp.

Statuses and errors

Every answer the API can give and every status a record can have, in one place. An error is answered with a JSON object: error (the code), message (a sentence in English) and, for invalid, field.

{"error":"invalid","field":"amount","message":"amount must be a positive decimal in KES, for example 25.00."}

HTTP statuses and error codes

• A batch with no events or more than 1,000 is refused with 422 invalid and no field.
• A 401 for a bad timestamp or signature with an operator key is listed in the inbound log as bad_signature. A request with an unknown key, or with an affiliate key, is not logged.
• A read answers 422 only for a report period that cannot be used (from and to). Any other parameter with a value that is not allowed is ignored and its default is used. Check the by, page and per_page in the answer.
• Retry on a timeout, on 429 and on 500. Do not retry any other 4xx unchanged.

What field names in a 422

The status of an event

In the answer to one event, and per event in results of a batch.

The effect of an event on the ledger

Commission types

Commission statuses

A row is written once and its amounts never change. Its status does:

Values of status_reason

Empty when a row only waits for its hold period, and normally for approved or paid commissions. A missing chargeback rate can also block an approved row. Fraud holds wait for the operator or the configured flag expiry.

Payout statuses

A month closes into a payout batch with one item per affiliate and currency. Batches and items are worked on in the portal; the API shows their result as the paid status of the commission rows.

Why a file row is refused

A refused row is counted in rejected, listed in problems as line N: reason, and kept in the inbound log with the line itself. Besides the reasons an event can be refused for:

• The line is not valid CSV.
• REG: registration_date or player_id is missing or cannot be read.
• SALES: activitydate or player_id is missing or cannot be read.
• SALES, revenue: the player is not registered.
• SALES, money: an amount is negative, unreadable or has too many decimals for its currency.
• SALES: the first-deposit amount exceeds gross deposits.
• SALES: an accepted day is re-exported with changed money totals, currency or timezone boundaries.
• SALES: known individual deposits or chargebacks exceed the day’s summary.
• SALES: first-deposit evidence conflicts with another day or a known transaction.
• SALES: an aggregate chargeback is ambiguous for first-deposit CPA of an already registered player.

Outcomes in the inbound log

States of a postback delivery

Statuses of an affiliate

The tracking link

A tracking link is opened by a visitor, not called by your platform. It stores the click and answers with a 302 redirect to the brand's landing page. Until the brand has verified its site, the visitor first sees a short page saying where the link leads. The destination host comes from the brand settings; a link can only choose a path on it.

GET https://track.revrake.com/c/a8Kq2Zx?sub1=TRACKER_CLICK_ID&utm_source=telegram

HTTP/1.1 302 Found
Location: https://your-site.example/landing?btag=1001_1&cid=01K6QF3M8Z5T7W9XB2C4D6E8GH&utm_source=telegram
Cache-Control: no-store

Parameters on the link

Parameters added to the landing URL

• If the landing URL of the brand contains {click_id} in its query, the click ID is put there and cid is not added.
• A click on the link of an affiliate who is not approved is stored and flagged, and lands without cid and btag: it cannot be attributed.
• Bots, link previews, HEAD requests, requests without a user agent and repeat clicks within the hour are stored and flagged, not dropped. Reports leave them out.
• Other parameters on the link are not stored and not passed on.
• A link the affiliate has given a short name also answers at /go/<name>, exactly as at /c/<code>. A brand with its own verified tracking domain serves both paths on that domain too.
• An unknown code is answered with 404 and an HTML error page, and so is a link whose brand has not set a destination yet.

Postbacks to affiliate trackers

This part needs no work from the operator. Each affiliate adds up to 10 destinations in their portal: an address template with macros, and the events to be told about. When an event is recorded for one of the affiliate's players, RevRake renders the template and calls it with a GET request.

Events

Status words per preset

A destination made from a preset sends, in {status}, the words its tracker knows. The presets of Voluum, PeerClick and FunnelFlux Pro, and "Other / custom", send the words of the table above. The words follow the preset the destination carries; its saved address is never changed.

Macros

A macro is a name in braces. It is replaced by its value, URL-encoded. Names are matched without regard to case. A name RevRake does not know is sent as written, so a typo shows in the delivery log. A value that is not known is empty.

Other names for the same macros

Trackers use different names for the same things. These are accepted as well:

Presets

The affiliate portal ships these templates. The affiliate replaces the host with their tracker's. Each follows its tracker's documentation: {conversion_id} is in the transaction parameter where the tracker updates a conversion that arrives again under the same ID, {event_id} where it would discard the later events.

An example

https://YOUR-TRACKER-DOMAIN/postback?click_id={sub1}&event={event}&status={status}&payout={commission}&currency={currency}&tid={conversion_id}&eid={event_id}

GET https://tracker.example/postback?click_id=TRACKER_CLICK_ID&event=ftd&status=sale&payout=40.00&currency=KES&tid=0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58&eid=0199b2c9-03aa-7e10-b6d2-91c07f5e2a18%3Aftd

Delivery

• A postback is queued in the same transaction as the event it reports, and sent within about ten seconds, oldest first.
• The request is a GET with the user agent RevRake-Postback/1. It follows at most three redirects and gives up after 5 seconds. Certificates are verified.
• A 2xx answer is a success. Anything else is a failure and is retried after 1 minute, 5 minutes, 25 minutes, 2 hours, 10 hours and 24 hours.
• After the last retry the delivery is marked as given up. The affiliate can send it again by hand.
• Every attempt is recorded with its duration, the status and the first 500 characters of the answer.
• After 5 and after 15 failures in a row the owner of the destination gets an email. At 20 the destination is switched off. Its deliveries, including those of events that happen while it is off, keep queuing and are sent when the affiliate switches it back on. A destination the affiliate switched off themselves gets nothing new.
• RevRake only calls public addresses. Loopback, private, link-local and carrier-grade NAT addresses are refused when the connection is made, so a redirect cannot get around it.
• The template must be a full http:// or https:// address of at most 2,000 characters.

Why an attempt failed

Operator webhooks

Webhooks tell the operator's own systems (a CRM, a data warehouse, a chat channel) what happens in the program. A workspace admin adds an endpoint on the Integration page of the operator portal: the address on your server, the events to send, and an optional description. For each of those events, RevRake sends a signed JSON POST to the address. Other team members cannot see or change the endpoints.

The address is a full https:// address on a public host (http:// is accepted, but use https://). Each endpoint has its own secret, which starts with whsec_. It is shown once, when the endpoint is created or its secret is rotated: copy it then. Rotating makes a new secret at once, and the old one stops signing.

An endpoint can also be a Slack or Microsoft Teams channel: choose “Slack message” or “Microsoft Teams message” and paste the channel's incoming-webhook address (for Teams, a workflow “When a Teams webhook request is received”). Each event then arrives as a sentence in the channel instead of signed JSON, and an amount can keep only first deposits from that size.

Events

Tick one or more per endpoint. The fields of data are described below; a field that does not apply is left out.

The body

Every request carries one JSON object:

{
  "id": "0199b2c9-0a11-7c3e-9f20-7d4b1e6a2c58",
  "type": "commission.created",
  "created_at": "2026-10-05T09:12:44.318204Z",
  "data": {
    "player_id": "PLR-1001",
    "occurred_at": "2026-10-05T09:12:40Z",
    "attributed": true,
    "affiliate_number": 1001,
    "affiliate_name": "Odds Garage",
    "commission_id": "0199b2c9-0a0f-7a51-8c3d-5e2f4a6b7c90",
    "commission_type": "cpa",
    "amount": "25.00",
    "amount_currency": "USD",
    "commission": "40.00",
    "commission_currency": "USD"
  }
}

Keys may come in any order, and the spacing of the JSON is not fixed. Verify the bytes as received, then parse them.

Headers

The request also carries Content-Type: application/json and the user agent RevRake-Webhook/1.

POST /revrake-webhook HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: RevRake-Webhook/1
RevRake-Event: commission.created
RevRake-Delivery: 0199b2c9-0b7e-7d02-8a41-3c5e6f708192
RevRake-Timestamp: 1791191571
RevRake-Signature: <hex HMAC-SHA256 of "1791191571.<raw body>">

The fields of data

Verify a request

1. Read the raw body as bytes, before any JSON parsing.
2. Check that RevRake-Timestamp is within 5 minutes of your clock, and refuse the request otherwise, so a recorded request cannot be played again later.
3. Compute the hex HMAC-SHA256 of the timestamp, a dot and the raw body under the endpoint's secret, and compare it with RevRake-Signature in constant time.
4. Only then parse the body. If you have already handled its id, answer 2xx and do nothing.
5. Answer with any 2xx within 5 seconds, and do slow work afterwards.

The same check in Node.js and Python, as the Integration page shows it:

const crypto = require("node:crypto");

// raw: the body exactly as received (a Buffer), before parsing it as JSON.
function verify(raw, headers, secret) {
  const ts = headers["revrake-timestamp"] ?? "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(ts + ".").update(raw).digest();
  const got = Buffer.from(headers["revrake-signature"] ?? "", "hex");
  return got.length === expected.length && crypto.timingSafeEqual(got, expected);
}

import hashlib, hmac, time

# raw: the body exactly as received (bytes), before parsing it as JSON.
def verify(raw: bytes, headers, secret: str) -> bool:
    ts = headers.get("RevRake-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("RevRake-Signature", ""))

Delivery, retries and switch-off

• A delivery is queued in the same transaction as the change it reports, so an event is sent if and only if the change was saved. It is sent within about ten seconds, oldest first.
• Delivery is at least once: the same event can arrive more than once, for example when your answer is lost on the way. Drop repeats by the body's id.
• Order is not guaranteed: a retry can arrive after a later event. Order events by created_at or occurred_at, not by the time they arrive.
• A 2xx answer within 5 seconds is a success. Anything else is a failure and is retried after 1 minute, 5 minutes, 25 minutes, 2 hours, 10 hours and 24 hours, with the same body and a fresh timestamp and signature.
• After the last retry the delivery is marked as given up. An admin can send it again from the delivery log; it then gets the whole retry schedule again.
• After 20 failed attempts in a row the endpoint is switched off. Its events keep queuing, and everything that queued is sent when an admin switches it back on. No email is sent when this happens: the state of each endpoint is on the Integration page.
• An endpoint you switch off yourself gets nothing new: no event is queued for it while it is off.
• RevRake calls public addresses only: it gives up after 5 seconds and verifies certificates. Loopback, private, link-local and carrier-grade NAT addresses are refused. A redirect is not followed: a 3xx answer is a failure with the error redirect, and the delivery log shows the address it pointed to.

Test it and read the delivery log

• Press "Send test" on an endpoint: a webhook.test event is sent at once, signed like a real one, and you see the status your endpoint answered and how long it took. A test is not retried, not listed in the delivery log and not counted as a failure.
• The delivery log of an endpoint shows its latest 100 deliveries: the event, the state (waiting, retrying, given up or delivered), the number of attempts, the last status or error, the first 500 characters of your answer, the next try, and the body as it was sent.
• A failed attempt is described with the same words as a postback (see why an attempt failed), plus redirect: your endpoint answered with a 3xx. The states are those of a postback delivery.

{
  "id": "0199b2d4-5c60-7b1a-9e3f-1a2b3c4d5e6f",
  "type": "webhook.test",
  "created_at": "2026-10-05T09:30:02.104377Z",
  "data": {
    "message": "A test from RevRake. If you can read this, your endpoint works."
  }
}

Best practice

• Keep the secret on your server, never in a page or an app. If it leaks, rotate it and move your endpoint to the new one right away: the old secret stops at once.
• Answer a request whose signature does not match with a 4xx. It is retried, signed with the current secret, so a delivery made while you rotate is not lost.
• Store the id of every event you have handled, and ignore an event you have seen.
• Answer first, work later: put the event on a queue of your own and answer 2xx, so a slow database never makes RevRake retry.
• Enter the final address of your endpoint. A redirect is not followed: the attempt fails with redirect, and the delivery log names the address to use instead.
• Use commission_id to join the events about one commission, and reconcile with GET /v1/commissions: a nightly read of the last 60 days catches anything that was missed.
• Tick only the events you use. Each one is a request to your server.

OpenAPI file

The four signed endpoints, with every status and reason as an enumeration, are described in openapi.yaml (OpenAPI 3.1), for code generators and API clients. Its address does not change.