Event Notifications

Webhooks

Webhooks enable MockPay to notify your application in real-time when transaction status changes occur. Configure your webhook URL in the Client Dashboard settings. All webhook events are scoped to your client account.

How It Works

Webhook Overview

When a transaction status changes (via manual override or automatic expiration), MockPay sends a POST request to your configured webhook URL containing the transaction details.

// Example Webhook Payload

{
    "event": "transaction.success",
    "timestamp": "2026-01-29T12:00:00Z",
    "data": {
        "transaction_id": "TRX-xxxxx",
        "order_id": "ORDER-12345",
        "amount": 100000,
        "status": "success",
        "payment_method": "bank_transfer",
        "payment_channel": "bca_va",
        "paid_at": "2026-01-29T12:00:00Z"
    }
}

Supported Events

Event Types

transaction.pending

Transaction created and waiting for payment

transaction.success

Payment received and transaction settled

transaction.failed

Payment failed

transaction.expired

Transaction expired without payment

transaction.cancelled

Transaction cancelled by merchant or system

transaction.refunded

Transaction refunded

Security

Signature Verification

To ensure webhook authenticity, verify the X-Mockpay-Signature header against the computed HMAC-SHA256 signature of the request body.

// PHP Signature Verification Example

$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhookSecret);
$headerSignature = $_SERVER['HTTP_X_MOCKPAY_SIGNATURE'] ?? '';

if (hash_equals($signature, $headerSignature)) {
    // Webhook is authentic — process the event
    $event = json_decode($payload, true);
    // Handle event based on $event['event'] type
} else {
    // Invalid signature — reject the request
    http_response_code(401);
    exit('Invalid signature');
}

Security Best Practice

Always verify webhook signatures before processing events. Use hash_equals() for timing-safe string comparison to prevent timing attacks.

Delivery

Retry Logic

MockPay automatically retries failed webhook deliveries using exponential backoff. The retry schedule is as follows:

1

Immediate

2

After 5 min

3

After 30 min

4

After 2 hours

Development Tip

Test webhooks locally using tools like webhook.site or ngrok to expose your local server to the internet.