Webhooks

Webhooks allow FinovoPay to send real-time HTTP POST notifications to your server. This is the recommended way to automate order fulfillment and update your database the moment a transaction is completed.

Security & Signature Verification

FinovoPay signs all webhook events by including a x-finovo-signature header. This is an HMAC SHA512 hash of the request payload, signed using your **Webhook Secret**.

Retrieve the raw JSON body from the incoming request.

Compute an HMAC SHA512 hash of the payload using your Secret Key.

Compare your calculated hash with the value in the header.

Verification Example (PHP)

webhook_handler.php

// Retrieve the request's body
$input = file_get_contents("php://input");
$sig = $_SERVER['HTTP_X_FINOVO_SIGNATURE'];
$secret = "YOUR_SECRET_KEY";

// Validate signature
$hash = hash_hmac('sha512', $input, $secret);

if($hash !== $sig){
    // This request did not come from FinovoPay!
    exit(http_response_code(401));
}

// Signature is valid, proceed with fulfillment
$event = json_decode($input);
// e.g., $event->data->transaction_ref;

Sample Event Payload

Event JSON

{
  "event": "transfer.success",
  "data": {
    "transaction_ref": "FP_CH_99A0B1C2D3",
    "amount": "15000.00",
    "currency": "NGN",
    "status": "success",
    "customer_email": "[email protected]",
    "paid_at": "2026-01-03 21:44:10"
  }
}

Delivery & Retries

If your server does not respond with a 200 OK within 10 seconds, FinovoPay will attempt to redeliver the notification up to **5 times** over a 24-hour period using exponential backoff.