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
| Event | Fired when |
|---|---|
| transfer.processing | A cross-border transfer entered the settlement rail. |
| transfer.completed | Funds delivered to the beneficiary. |
| transfer.failed | Delivery failed; funds returned to your wallet. |
| payout.completed | A local payout was credited. |
| payout.failed | A local payout was rejected by the destination bank. |
| bill.completed | A bill payment received value confirmation from the biller. |
| card.transaction | A virtual card was authorised, charged, refunded or declined. |
| card.terminated | A 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
- If your endpoint does not return
2xx, we retry with exponential backoff for up to 24 hours (8 attempts). - Events can arrive out of order — use
created_atand the object'sstatusrather than assuming sequence. - Deliveries can occasionally duplicate — treat
event.idas an idempotency key and skip events you have already processed.
Testing: in sandbox, every money-movement flow completes automatically after ~30 seconds, so you can exercise your full webhook handling without real funds.