DocsPostback Delivery & Troubleshooting

Postback Delivery & Troubleshooting

Firewall configuration, webhook delivery security, retry schedules, and common postback errors.

Firewall & Security Allowlisting

If your backend server sits behind a firewall (Cloudflare WAF, AWS Security Group, iptables, or ModSecurity), ensure your webhook endpoint allows incoming automated HTTP delivery from Perkox.

Cryptographic HMAC Verification (Recommended)
Perkox dispatches postbacks from a resilient, distributed cloud proxy network. Rather than configuring brittle IP allowlists that require manual updates during infrastructure maintenance, we strongly recommend securing your webhook endpoint using HMAC-SHA256 signature verification.
Validating the &signature= parameter guarantees webhook authenticity and tamper-proofing with zero firewall maintenance. See the Postback Security & HMAC Guide.

Official Egress IP Allowlist (Cloudflare Anycast)

All outbound Perkox conversion callbacks originate from these global edge CIDR blocks.

173.245.48.0/20
103.21.244.0/22
103.22.200.0/22
103.31.4.0/22
141.101.64.0/18
108.162.192.0/18
190.93.240.0/20
188.114.96.0/20
197.234.240.0/22
198.41.128.0/17
162.158.0.0/15
104.16.0.0/13
104.24.0.0/14
172.64.0.0/13
131.0.72.0/22
Synchronized with Cloudflare's published global edge network (cloudflare.com/ips).Always combine with {signature} verification.
Why Two-Tier Security Matters

Tier 1 (Firewall Allowlisting): Restricting traffic to Cloudflare Anycast CIDRs prevents unauthorized internet bots and malicious port scanners from ever probing your webhook URL.

Tier 2 (Cryptographic Authentication): Because Cloudflare edge IPs are shared across their global CDN network, validating the {signature} macro proves that the callback was specifically dispatched from your verified Perkox publisher account.

Expected Response Codes

HTTP 200 OK

Acknowledges successful processing. Perkox marks the postback as delivered and halts further retries.

HTTP 4xx / 5xx / Timeout

Treated as delivery failure. Perkox queues the postback for automated exponential retry.

Retry Policy & Backoff

If your server is down or returns an error, Perkox automatically retries delivery up to 10 times over a 24-hour window using exponential backoff:

  • Attempt 1: Immediately upon completion
  • Attempt 2: 1 minute later
  • Attempt 3: 5 minutes later
  • Attempt 4: 15 minutes later
  • Attempt 5: 1 hour later
  • Attempts 6-10: Every 4 hours up to 24 hours total

Debugging with cURL

You can simulate an incoming Perkox postback to your local or staging server using cURL:

curl -i -X GET 'https://api.yourdomain.com/postback?player_id=test_user&reward_amount=100&payout=1.00&click_id=test_clk_001&status=approved&signature=YOUR_CALCULATED_HASH'
Timeout Threshold
Perkox sets an HTTP connection timeout of 5 seconds. If your server takes longer than 5 seconds to respond (e.g. performing heavy synchronous database locks), the connection will be aborted. We recommend responding with HTTP 200 immediately and processing user crediting in a background queue.