Affiliate Postback Engine

Power Your Attribution with Server-to-Server Postback Tracking ⚡

A lightweight affiliate postback tracking system 🚀 built with Node.js, Postgres, and Next.js. It lets affiliates track clicks, record conversions via server-to-server postbacks, and monitor results in a sleek dashboard. Designed as an MVP, it highlights the core principles of affiliate tracking and attribution—simple, clear, and extendable. Perfect for learning or building upon in real-world projects. 📊

📡 What is Server-to-Server (S2S) Tracking?

Server-to-Server (S2S) tracking is a method where conversion events are transmitted directly between servers, instead of relying on browser scripts or cookies. This approach delivers higher accuracy, stronger security, and immunity to ad blockers, making it the gold standard in modern affiliate marketing. By cutting out client-side dependencies, S2S ensures that every click and conversion is logged reliably, even in environments where cookies are restricted.

🧩 Application & MVP

This project is a minimal viable product (MVP) of an affiliate tracking engine, built for clarity and extendability.

It demonstrates the core building blocks of affiliate attribution:

Click Storage: Log and map affiliate clicks with campaigns.
Postback Handling: Receive advertiser postbacks securely.
Click-to-Conversion Match: Attribute conversions to the right clicks.
Dashboard Insights: Visualize clicks and conversions in real time.
Lightweight & Extendable: Designed as a foundation to build upon.

🔑 Key Features

🎯 Click Tracking: Map affiliates and campaigns seamlessly for accurate attribution.
🔗 Secure Postbacks: Record conversions safely through server-to-server endpoints.
🛠️ Unique URLs: Auto-generate affiliate-specific postback links with ease.
📊 Modern Dashboard: View clicks and conversions in a clean, intuitive interface.
🛡️ Fraud Prevention: Validate clicks before logging conversions to ensure trust.
🗄️ Postgres-Powered: Scalable storage backed by PostgreSQL for reliability.

Demo 🖥️

Important

Use the Docker image or run locally via localhost to get started now.

You can visit the live site here : --Temporarily Not Deployed--

🛠️ Technologies Used

Node.js (Express) → Backend API for clicks and postbacks
PostgreSQL → Relational database for affiliates, clicks, conversions
Next.js (React) → Frontend affiliate dashboard with SSR
Tailwind CSS → Modern utility-first styling for responsive UI
REST API → Communication between frontend, backend, and database
Git & GitHub → Version control and collaborative development
Docker → A container platform for easy deployment, scalability, and app management.

Getting Started ⚙️

Prerequisites

Node.js v22.14.0 or higher
pnpm or npm (package managers)
Code Editor (e.g., VS Code)
Git (version control system)
Docker (for containerized deployments)
PostgreSQL (relational database)
Modern Browser (latest Chrome, Firefox, or Edge for development/testing)

Installation 🛠️

First Read this License & their terms then proceed.
Star ⭐ the Repository
Fork the repository (Optional)
Project Setup:

Clone the repository:

    git clone https://github.com/UjjwalSaini07/Affiliate-Postback-Engine.git

Navigate to the project main directory:

    cd Affiliate-Postback-Engine

Important

All these cd directory paths are relative to the root directory of the cloned project.

Frontend Setup:

Navigate to the project Frontend directory:

    cd frontend

Install Frontend dependencies:

    pnpm install

Backend Setup:

Navigate to the project Backend directory:

    cd backend

Install Backend dependencies:

    pnpm install

Open Docker Engine:

    cd Affiliate-Postback-Engine

Start PostgreSQL from Docker: Before that Install Locally

    docker compose up -d

    docker compose ps

Here’s how it looks

It Open the Database on Port - 5432

Start the web app 🖥️

For Frontend

Start the Frontend Development server

    cd frontend

    pnpm dev

Frontend Operates on Port: http://localhost:3000

For Backend

Start the Backend Development server

    cd backend

    pnpm dev

Backend Operates on Port: http://localhost:4000

For Database

You can run it using Docker or initialize it locally with the PostgreSQL command-line service — it depends on how you prefer to start the database engine.
Database Operates on Port: http://localhost:5433

Project Setup Using Docker Containerization:

Start the Docker Engine Locally or Use Any Service Globally
Navigate to the project Root directory:

    cd Affiliate-Postback-Engine

Run DockerFile:

    docker-compose up --build

Wait for Generating the Image

How Docker Image Builds Looks

Now Simply use the Project using Docker Container
If u Want Direct Image Without Cloning So Contact with Me. Contact

📡 API Endpoints & Requests Procedure

This project provides lightweight yet powerful tracking and postback APIs designed for affiliate marketing workflows.
Current MVP implementation uses GET requests for simplicity (future versions will support POST with JSON payloads for better scalability).
Each endpoint is designed with idempotency in mind, ensuring duplicate clicks or conversions are safely ignored.
Responses are JSON formatted, making them easy to consume programmatically or test manually.
Built for real-world extensibility: future improvements will include authentication, HMAC signing for postbacks, and rate limiting for better security and reliability.
Can be easily tested using curl, Postman, or Hoppscotch without any extra setup.

🔗 Endpoints Overview

Log a Click: GET /click?affiliate_id=&campaign_id=&click_id=
Send a Postback (Conversion): GET /postback?affiliate_id=&click_id=&amount=&currency=
List Affiliates: GET /affiliates
Get All Clicks for an Affiliate: GET /affiliates/:id/clicks
Get All Conversions for an Affiliate: GET /affiliates/:id/conversions

⚡ Testing of the Requests (cURL) - Use Postman

📍 Log a click

    curl "http://localhost:4000/click?affiliate_id=1&campaign_id=1&click_id=abc123"

📍 Send a postback (conversion)

    curl "http://localhost:4000/postback?affiliate_id=1&click_id=abc123&amount=100&currency=USD"

📍 Check for Error- Something Went Wrong {Passes Wrong Payload}

    curl "http://localhost:4000/postback?affiliate_id=2&click_id=abc123&amount=100&currency=USD"

📍 Get conversions for affiliate 1

    curl "http://localhost:4000/affiliates/1/conversions"

Image Reference for Postman API Hiting

Curl Request 1: GET Method - Log a click

Curl Request 2: GET Method - Send a postback (conversion)

Curl Request 3: GET Method - Check for Error

Curl Request 4: GET Method - Get conversions for affiliate

DataBase Setup Locally ⚙️

🔎 Quick Check

Open Powershell or Cmd on dir - cd Affiliate-Postback-Engine
Run this to view all conversions joined with their clicks (ordered by affiliate):

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    SELECT c.id, c.amount, c.currency, cl.click_id, cl.affiliate_id
    FROM conversions c
    JOIN clicks cl ON c.click_id = cl.id
    ORDER BY cl.affiliate_id;"

Check if click exists

🔍 Individual Check

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    SELECT * FROM clicks WHERE affiliate_id = 3 AND click_id = 'abc999';"

If 0 rows returned, insert the click first:

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO clicks (affiliate_id, campaign_id, click_id)
    VALUES (3, 2, 'abc999')
    ON CONFLICT (affiliate_id, campaign_id, click_id) DO NOTHING;"

Adjust campaign_id to a valid campaign for that affiliate.

Insert conversion safely

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO conversions (click_id, amount, currency)
    VALUES ((SELECT id FROM clicks WHERE affiliate_id = 3 AND click_id = 'abc999'), 200, 'USD')
    ON CONFLICT (click_id) DO NOTHING;"

Important Alter Table Commands

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO clicks (click_id, affiliate_id, campaign_id)
    VALUES ('usgs07', 1, 2)
    ON CONFLICT (click_id) DO NOTHING;"

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO conversions (click_id, amount, currency)
    VALUES (
      (SELECT id FROM clicks WHERE click_id = 'valid123' LIMIT 1), 550, 'USD')
    ON CONFLICT (click_id) DO NOTHING;"

Image Reference

Data Adding in Database

Affiliate Dev Table Showcasing

PostgreSQL and PgAdmin 4

📊 Sample Test Data Inserts

Affiliate 1 – Clicks & Conversions

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO clicks (affiliate_id, campaign_id, click_id)
    VALUES 
      (1, 1, 'abc123'),
      (1, 1, 'def456')
    ON CONFLICT (affiliate_id, campaign_id, click_id) DO NOTHING;"
    
    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO conversions (click_id, amount, currency)
    VALUES
      ((SELECT id FROM clicks WHERE affiliate_id = 1 AND click_id = 'abc123'), 100, 'USD'),
      ((SELECT id FROM clicks WHERE affiliate_id = 1 AND click_id = 'def456'), 150, 'USD')
    ON CONFLICT (click_id) DO NOTHING;"

Affiliate 2 – Clicks & Conversions

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO clicks (affiliate_id, campaign_id, click_id)
    VALUES 
      (2, 2, 'xyz999'),
      (2, 2, 'uvw111')
    ON CONFLICT (affiliate_id, campaign_id, click_id) DO NOTHING;"
    
    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO conversions (click_id, amount, currency)
    VALUES
      ((SELECT id FROM clicks WHERE affiliate_id = 2 AND click_id = 'xyz999'), 50, 'USD'),
      ((SELECT id FROM clicks WHERE affiliate_id = 2 AND click_id = 'uvw111'), 75, 'USD')
    ON CONFLICT (click_id) DO NOTHING;"

Affiliate 3 – Clicks & Conversions

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO clicks (affiliate_id, campaign_id, click_id)
    VALUES 
      (3, 1, 'lmn123'),
      (3, 1, 'opq456')
    ON CONFLICT (affiliate_id, campaign_id, click_id) DO NOTHING;"
    
    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "
    INSERT INTO conversions (click_id, amount, currency)
    VALUES
      ((SELECT id FROM clicks WHERE affiliate_id = 3 AND click_id = 'lmn123'), 120, 'USD'),
      ((SELECT id FROM clicks WHERE affiliate_id = 3 AND click_id = 'opq456'), 90, 'USD')
    ON CONFLICT (click_id) DO NOTHING;"

🔒 Security & Correctness Notes

Validation: Every conversion request validates that the given affiliate_id and click_id pair exists before inserting. This ensures conversions cannot be logged against mismatched or invalid clicks.
Idempotency:
- The conversions table enforces a UNIQUE(click_id) constraint to guarantee no duplicate conversions for the same click.
- The /postback route also performs a check and returns 409 Conflict if a duplicate is attempted.
SQL Injection Prevention: All database interactions use parameterized queries ($1, $2, …) to safely handle user input.
Optional Security Improvements:
- HMAC-Signed Postbacks: Advertisers could sign each postback request using a shared secret.
- The backend would verify the signature before processing, ensuring requests cannot be forged or tampered with.
Caveat (MVP Limitation):
- Current implementation uses GET requests for simplicity (common in affiliate postback flows).
- Future iterations should move to POST + JSON body + HMAC for stronger security and industry alignment.

Install PostgreSQL

PostgreSQL as a Client

Install Postgres locally:
Download from: https://www.postgresql.org/download/windows/
During setup, tick “Command Line Tools”.
Open a new PowerShell or Git Bash and run:

    psql -U postgres -h localhost -p 5432 -d affiliate_dev -f db/schema.sql

Use Docker’s built-in psql inside your container

If you’re running Postgres in Docker (like we set up with docker-compose.yml)

    docker exec -it affiliate-postback-engine-db-1 psql -U postgres -d affiliate_dev -f /docker-entrypoint-initdb.d/schema.sql

But for that to work, you’d need to copy your schema.sql and seed.sql into the container first

    docker cp db/schema.sql affiliate-postback-engine-db-1:/docker-entrypoint-initdb.d/schema.sql

    docker cp db/seed.sql affiliate-postback-engine-db-1:/docker-entrypoint-initdb.d/seed.sql

Then run the docker exec command.
Test connection

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "\dt"

Just same as in this Image

Important

If this is Not shown on Test Connection So Follow Below Procedure Step By Step, Author: UjjwalS

Setup Database

Step 1: Create the database

    psql -U postgres -h localhost -p 5433 -c "CREATE DATABASE affiliate_dev;"

Enter your password when prompted.

Step 2: Apply schema

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -f db/schema.sql

Step 3: Seed sample data

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -f db/seed.sql

Step 4: Verify tables exist

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "\dt"

Your database setup is complete with seed data and schema synchronization.
Load sample data

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -f db/seed.sql

Then check

    psql -U postgres -h localhost -p 5433 -d affiliate_dev -c "SELECT * FROM affiliates;"

Resources 📚

Author ✍️

@Ujjwal Saini

Screenshots 📷

Terminal Data fetching

Contact 📞

Feel free to reach out if you have any questions or suggestions!

Raise an issue for the same Issue
Github: @Ujjwal Saini

License 📄

License Credential LICENSE

Feedback and Contributions 💌

Sorry But this repository not welcome Contributions! Yes u gave a Feedback and Suggestion via raising the Issue.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github		.github
backend		backend
db		db
frontend		frontend
nginx		nginx
release		release
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
run-nginx.sh		run-nginx.sh

License

UjjwalSaini07/Affiliate-Postback-Engine

Folders and files

Latest commit

History

Repository files navigation

Affiliate Postback Engine

📡 What is Server-to-Server (S2S) Tracking?

🧩 Application & MVP

🔑 Key Features

Demo 🖥️

🛠️ Technologies Used

Getting Started ⚙️

Prerequisites

Installation 🛠️

Frontend Setup:

Backend Setup:

Open Docker Engine:

Here’s how it looks

Start the web app 🖥️

For Frontend

For Backend

For Database

Project Setup Using Docker Containerization:

How Docker Image Builds Looks

📡 API Endpoints & Requests Procedure

🔗 Endpoints Overview

⚡ Testing of the Requests (cURL) - Use Postman

Image Reference for Postman API Hiting

Curl Request 1: GET Method - Log a click

Curl Request 2: GET Method - Send a postback (conversion)

Curl Request 3: GET Method - Check for Error

Curl Request 4: GET Method - Get conversions for affiliate

DataBase Setup Locally ⚙️

🔎 Quick Check

Check if click exists

Image Reference

Data Adding in Database

Affiliate Dev Table Showcasing

PostgreSQL and PgAdmin 4

📊 Sample Test Data Inserts

Affiliate 1 – Clicks & Conversions

Affiliate 2 – Clicks & Conversions

Affiliate 3 – Clicks & Conversions

🔒 Security & Correctness Notes

Install PostgreSQL

Just same as in this Image

Setup Database

Step 1: Create the database

Step 2: Apply schema

Step 3: Seed sample data

Step 4: Verify tables exist

Resources 📚

Author ✍️

Screenshots 📷

Terminal Data fetching

Contact 📞

License 📄

Feedback and Contributions 💌

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Languages