Support
Getting started

Webhooks

Webhooks push events to your server the moment something happens — a transfer settles, a payout fails, a card is charged. Subscribe instead of polling.

Setup

Add your endpoint under Settings → Webhooks in the dashboard. Each environment has its own endpoints and its own signing secret (whsec_...). Your endpoint must accept POST requests over HTTPS and respond with a 2xx within 10 seconds.

Event payload

POST to your endpoint
{
  "id": "evt_2k9df13a",
  "type": "transfer.completed",
  "created_at": "2026-07-10T14:03:22Z",
  "data": {
    "id": "tr_9x2m1kd8",
    "status": "completed",
    "source_amount": 1000,
    "source_currency": "USD",
    "destination_amount": 1534500,
    "destination_currency": "NGN",
    "reference": "INV-2041"
  }
}

Event types

EventFired when
transfer.processingA cross-border transfer entered the settlement rail.
transfer.completedFunds delivered to the beneficiary.
transfer.failedDelivery failed; funds returned to your wallet.
payout.completedA local payout was credited.
payout.failedA local payout was rejected by the destination bank.
bill.completedA bill payment received value confirmation from the biller.
card.transactionA virtual card was authorised, charged, refunded or declined.
card.terminatedA card was terminated (by you or by risk controls).

Verify signatures

Every delivery includes an X-Finlogic-Signature header — an HMAC SHA-256 of the raw request body using your endpoint's signing secret. Always verify it before trusting the payload:

PHP
$payload   = file_get_contents('php://input');
$signature = isset($_SERVER['HTTP_X_FINLOGIC_SIGNATURE']) ? $_SERVER['HTTP_X_FINLOGIC_SIGNATURE'] : '';
$expected  = hash_hmac('sha256', $payload, getenv('FINLOGIC_WEBHOOK_SECRET'));

if (!hash_equals($expected, $signature)) {
    http_response_code(400);
    exit('Invalid signature');
}

$event = json_decode($payload, true);

switch ($event['type']) {
    case 'transfer.completed':
        // mark the order as paid
        break;
    case 'transfer.failed':
        // alert your ops team, refund the customer
        break;
}

http_response_code(200);

Retries & ordering

Testing: in sandbox, every money-movement flow completes automatically after ~30 seconds, so you can exercise your full webhook handling without real funds.