Postback Manager

A WordPress plugin for query-parameter driven postback execution, redirect handling, retry logic, and reporting.

This plugin started as a private operational tool and was later refactored into a more generic public-facing version. The current scope is a solid plugin prototype suitable for GitHub release first, with marketplace hardening later.

What It Does

• watches selected query parameters on incoming traffic
• redirects matching visits through a controlled /redirect flow
• resolves macros like {click_id} and {zone_id} in postback and redirect URLs
• enqueues postback execution instead of firing everything inline
• retries failed postbacks
• stores runtime logs in a custom WordPress DB table
• shows both summary and row-level logs in the admin page

Key Ideas

• Postback Summary
  • aggregated counts by selected parameters
  • intended for quick overview
• Recent Logs
  • row-level operational truth
  • intended for debugging and reporting

flowchart TD
    A[Visitor hits site with query params] --> B[auto-redirect.js]
    B --> C[Redirect route]
    C --> D[redirect.js]
    D --> E[Enqueue endpoint]
    E --> F[Queued cron event]
    F --> G[queue_runner fires postback]
    G --> H[Custom log table]
    D --> I[Log endpoint]
    I --> H
    H --> J[Admin Summary]
    H --> K[Recent Logs]

Current Features

• configurable allowed query parameters
• configurable redirect URL template
• configurable postback URL template
• configurable retry count and retry delay
• dynamic summary table based on selected summary parameters
• recent log table based on stored params_json
• WordPress-native settings storage via wp_options
• custom DB table for log/history storage
• rewrite-based redirect route
• admin-only report endpoint

Configuration

Main settings:

• Allowed Query Parameters
  • comma-separated parameter list, for example:
  • click_id, zone_id
• Summary Parameters
  • selected from allowed parameters
  • used for the summary matrix only
• Redirect URL
  • supports macros such as {click_id}
• Postback URL
  • supports macros such as {click_id} and {zone_id}
• Max Retries
• Retry Delay (seconds)

Example

Allowed params:

click_id, zone_id

Redirect URL:

https://example.com/final?click_id={click_id}

Postback URL:

https://postman-echo.com/get?click_id={click_id}&zone_id={zone_id}

Incoming request:

https://your-site.test/?click_id=abc123&zone_id=header

Resolved postback request:

https://postman-echo.com/get?click_id=abc123&zone_id=header

Local Development

This repo includes a wp-env setup for local plugin testing.

Files:

• .wp-env.json
• LOCAL_DEV.md

Recommended local flow:

1. start Docker Desktop
2. use WSL for the local development copy
3. run npx wp-env start
4. activate the plugin in WordPress admin

Useful commands we used during setup:

# copy the project from Windows into the WSL home directory
cp -r "/mnt/d/Code/PHP/Wordpress Custom Plugin/Postback Manager/postback-manager" ~/projects/postback-manager

# or sync updates without rebuilding the whole environment
rsync -av --delete "/mnt/d/Code/PHP/Wordpress Custom Plugin/Postback Manager/postback-manager/" ~/projects/postback-manager/

# verify Docker is available inside WSL
docker version

# install wp-env locally for the project
npm install --save-dev @wordpress/env

# start or stop the WordPress environment
npx wp-env start
npx wp-env stop
npx wp-env destroy

# inspect plugins from the CLI container
npx wp-env run cli wp plugin list
npx wp-env run cli wp plugin activate postback-manager

# inspect DB table state
npx wp-env run cli wp db query "SHOW TABLES LIKE '%postback_manager_logs%';"
npx wp-env run cli wp db query "SELECT id, created_at, status, source, retry_count FROM wp_postback_manager_logs ORDER BY id DESC LIMIT 20;"

# inspect and force cron execution
npx wp-env run cli wp cron event list
npx wp-env run cli wp cron event run --due-now

If you hit Node networking issues in WSL, this helped during setup:

export NODE_OPTIONS="--network-family-autoselection-attempt-timeout=5000 --dns-result-order=ipv4first"

Report Access

Current state:

• /report is admin-only in the refactored public version

Planned future option:

• admin-generated tokenized report access
• intended for non-admin consumers who need read access without direct admin help
• token generation and revoke flow should be admin-controlled

This tokenized report access is a planned enhancement, not part of the current stable scope.

Non-Goals

• full analytics platform
• campaign-provider-specific hardcoding
• public unauthenticated reporting by default
• external dashboard/frontend app
• plugin marketplace submission in the current state

Status

GitHub-ready prototype.

The plugin is already functionally solid enough for public source release. Marketplace submission should happen only after additional security, packaging, and UX hardening.

License

This project is released under a custom non-commercial attribution license. See LICENSE.