How FamGateway™ Webhooks Work: Pure-PHP Architecture, HMAC Security & Official PHP SDK

In mission-critical fintech applications, payment verification cannot rely on fragile browser redirects. Customers frequently close browser tabs immediately after seeing a UPI success tick, drop network connectivity on mobile 4G/5G, or experience app crashes. Here is the complete architectural and engineering blueprint of the FamGateway™ Webhook Delivery Engine — built on a lightweight, high-performance Pure PHP and MySQL stack, and how to integrate it using our official open-source FamGateway PHP SDK.

1. Official Open-Source PHP SDK on GitHub

To make payment creation and webhook verification seamless for developers, we maintain an official zero-dependency PHP SDK on GitHub:

2. Quantitative Performance & Architecture Benchmarks

Here is an empirical comparison of how FamGateway's webhook architecture compares with traditional custodial payment aggregators and manual UTR verification:

Evaluation Metric	FamGateway Engine	Traditional Gateways	Manual Verification
Verification Latency	1.5 – 3.5 seconds	2.0 – 5.0 seconds	5 – 30 minutes
Fund Settlement	Instant (0s, Direct UPI)	T+2 Business Days	Instant (Manual)
Transaction Commission	0% (Free Forever)	2.0% – 3.0% + GST	0%
Cryptographic Auth	HMAC-SHA256 Signed	HMAC / Basic Secret	None (Screenshot fake risk)
Double-Spending Lock	Atomic DB UTR Unique	Aggregator Controlled	High Human Error Risk
Automated Retries	4 Retries (0, 5m, 10m, 15m)	Variable (3-5 Retries)	No Retry Capability

3. The Problem: Why Client-Side Redirects Fail

Traditional payment setups often redirect the customer's browser from the payment page back to a merchant URL (such as https://yoursite.com/success.php?order_id=123). In high-volume production environments, between 8% and 14% of successful payments are lost or abandoned at this stage due to:

• Immediate App Switching: Users tap 'Done' or swipe away the mobile browser immediately after viewing their UPI app confirmation screen.
• Mobile Network Handover Failures: Network latency spikes or mobile data disconnects during the bank-to-merchant browser redirect.
• Aggressive OS Tab Discarding: Mobile browsers (such as Chrome and Safari on iOS/Android) frequently suspend background tabs to save battery when a user opens PhonePe, Google Pay, or FamApp.

FamGateway eliminates this vulnerability through Server-to-Server Webhooks (Instant Payment Notifications) that communicate directly between our backend and your server within milliseconds of payment clearance.

3. Pure-PHP & MySQL Webhook Pipeline Architecture

Unlike complex systems that require heavy Node.js or Python daemons, FamGateway is engineered entirely in Pure PHP and MySQL for maximum speed, security, and low server resource consumption. Learn how this fits into our broader Non-Custodial Architecture:

4. Preventing Double Payments & Replay Attacks

One of the hardest challenges in peer-to-peer UPI automation is preventing bad actors from submitting the same UTR multiple times or replaying old webhook notifications to receive duplicate product deliveries.

FamGateway defends against these exploits at three distinct engineering layers:

A. Unique Order Reference Embedding in UPI QR

Every dynamic QR code generated by FamGateway encodes a unique, deterministic transaction reference note (such as FamGateway-ORD68F921B). When the customer pays, this note is permanently attached to the bank receipt, allowing our matching engine to bind the incoming payment to exactly one order.

B. Atomic Database Locks (UTR Deduplication)

The database enforces strict uniqueness on transaction UTRs. Once a UTR is recorded for an order, any subsequent attempt by a user or script to submit that same UTR for another invoice is rejected instantly with an HTTP 409 Conflict status.

C. Webhook Payload Timestamps

Every webhook payload includes a Unix timestamp field representing the exact second the event was generated. Merchant servers can verify that the timestamp is within a 5-minute tolerance window to discard stale replay attacks.

5. Standardized JSON Payload Specification

FamGateway delivers a standardized, strongly typed JSON payload across all webhook events:

{
  "event": "payment.success",
  "order_id": "ORD-68F921B",
  "amount": "499.00",
  "payable_amount": "499.00",
  "status": "success",
  "transaction_id": "TXN_881920394",
  "utr": "423189021345",
  "sender_name": "Rahul Kumar",
  "payment_time": "30-08-2026 19:20:15",
  "timestamp": 1788098415
}

Field Name	Type	Description
event	String	Event type identifier (e.g., payment.success).
order_id	String	The unique merchant order ID provided during creation.
amount	String	Original order amount requested in INR.
payable_amount	String	Actual amount verified and paid by the sender.
status	String	Payment state (success).
utr	String	12-digit official bank UPI Reference Number.
sender_name	String	Name of the customer who completed the UPI transfer.
timestamp	Integer	Unix epoch timestamp when the webhook was generated.

6. Integration via Official FamGateway PHP SDK

Integrating webhook verification takes just a few lines of code with FamGateway.php from the official GitHub SDK:

Handling Webhooks in PHP (webhook.php)

<?php
// Include the official FamGateway PHP SDK
require_once 'FamGateway.php';

// 1. Initialize SDK with your Secret API Key
$fam = new FamGateway("sk_live_YOUR_API_KEY_HERE");

// 2. Read raw POST data and incoming signature header
$rawPostData = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FAMGATEWAY_SIGNATURE'] ?? '';

// 3. Verify the signature securely
$data = $fam->verifyWebhook($rawPostData, $signature);

if ($data !== false) {
    // Signature verified and authentic!
    $event = $data['event'];
    
    if ($event === 'payment.success') {
        $orderId = $data['order_id'];
        $amount = $data['amount'];
        $utr = $data['utr'];
        $transactionId = $data['transaction_id'];
        
        // Execute your database fulfillment logic idempotently
        // markOrderPaidInDatabase($orderId, $utr, $amount);
        
        http_response_code(200);
        echo "Webhook processed successfully.";
    } else {
        http_response_code(200);
        echo "Event ignored.";
    }
} else {
    // Forged or invalid signature
    http_response_code(403);
    echo "Invalid signature.";
}
?>

Creating a Payment Order with Custom Webhook URL

<?php
require_once 'FamGateway.php';

$fam = new FamGateway("sk_live_YOUR_API_KEY_HERE");

// Automatically creates the order and redirects to secure checkout
$amount = 299.00;
$redirectUrl = "https://yourwebsite.com/success.php";
$customWebhookUrl = "https://yourwebsite.com/api/payment-callback.php";

$fam->createPayment($amount, $redirectUrl, $customWebhookUrl);
?>

7. Pure PHP Manual Verification (Without SDK)

If you prefer writing native PHP code without including the SDK file, here is the exact verification algorithm:

<?php
$apiKey = "YOUR_FAMGATEWAY_API_KEY";

// 1. Read raw body and signature header
$rawBody = file_get_contents("php://input");
$receivedSignature = $_SERVER['HTTP_X_FAMGATEWAY_SIGNATURE'] ?? '';

if (empty($rawBody) || empty($receivedSignature)) {
    http_response_code(400);
    echo json_encode(["status" => "error", "message" => "Missing payload or signature"]);
    exit;
}

// 2. Compute expected HMAC-SHA256 signature
$expectedSignature = hash_hmac('sha256', $rawBody, $apiKey);

// 3. Constant-time comparison to prevent timing attacks
if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    echo json_encode(["status" => "error", "message" => "Invalid signature"]);
    exit;
}

// 4. Decode payload and fulfill order
$data = json_decode($rawBody, true);
if (($data['event'] ?? '') === 'payment.success') {
    $orderId = $data['order_id'];
    $utr = $data['utr'];
    $amount = $data['amount'];
    
    // Fulfill order
    http_response_code(200);
    echo json_encode(["status" => "success"]);
}
?>

8. Automated Exponential Retry Schedule

If your destination server is temporarily unresponsive or returns a 5xx/4xx error code, FamGateway does not discard the transaction event. The background engine manages an automated retry schedule:

Delivery Attempt	Timing Delay	Condition	Status Outcome
Attempt 1 (Immediate)	0 seconds	Bank email matched and verified	Completed on 2xx response
Attempt 2 (Retry 1)	+5 minutes	Attempt 1 timeout or non-2xx	Re-queued in scheduler
Attempt 3 (Retry 2)	+10 minutes	Attempt 2 timeout or non-2xx	Re-queued in scheduler
Attempt 4 (Final Retry)	+15 minutes	Attempt 3 timeout or non-2xx	Permanently marked Failed

9. Developer Observability & Sandbox Testing

Inside the FamGateway Dashboard → Webhooks section, developers have access to complete testing and monitoring tools:

• Test & Verify Button: Fires a simulated sandbox payload with the signature to test server connectivity before going live.
• Live Audit Logs: Displays recent webhook history, including timestamps, raw payloads, HTTP response codes, latency, and cURL error diagnostics.
• SSRF Network Defense: Outbound deliveries to loopback (127.0.0.1) and private subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are strictly blocked.

Frequently Asked Questions

Ready to Automate Your Payment Workflows?

Get instant zero-fee FamPay UPI webhooks, complete REST API documentation, and direct bank settlements today.

Get Your Free API Key →

Back to Homepage →