Nigerian users expect instant feedback when they make a payment. If your app takes more than a few seconds to confirm a transaction, users assume something went wrong and may abandon your platform. This guide covers building a multi-channel real-time notification system that delivers under 10 seconds.
Webhooks are the backbone of payment notifications. When a transaction completes, the payment provider sends an HTTP POST request to your server with the full transaction details including amount, reference, status, and customer information. Your webhook endpoint must be publicly accessible on the internet and configured with the correct URL in your payment provider dashboard. Security is critical because anyone who discovers your webhook URL could send fake payment notifications.
Paystack sends webhook events for charge.success, charge.failure, transfer.success, and transfer.failure. Every incoming webhook must be verified using HMAC-SHA256 with your secret key by computing the signature on your end and comparing it against the X-Paystack-Signature header value. Any webhook that fails signature verification must be rejected with a 400 status code and logged for security monitoring. Paystack retries failed deliveries up to 7 times over approximately 2 hours using exponential backoff starting at 10 seconds and increasing to a maximum of 10 minutes between retries.
Flutterwave uses a verification hash sent in the request header that you validate using your secret key. Their event types include charge.completed, charge.failed, and various transfer status events. The Flutterwave retry schedule extends to 10 attempts over a 24-hour period, giving your system more time to recover from outages. Most Nigerian fintech apps integrate both payment providers for redundancy, and your webhook endpoint must be able to handle both providers webhook formats. Your endpoint should respond with a 200 OK status immediately upon receiving a verified webhook, then process the event asynchronously in a background job queue to avoid timeout risks.
Webhooks notify your backend server when a payment event occurs, but WebSockets push that update to the users mobile or web app in real time without requiring the user to refresh or poll. When your server receives a webhook confirming payment, your WebSocket server publishes the update to that users specific connection channel in under 200 milliseconds. The app immediately displays a success screen with the transaction details, updates the wallet balance, or enables the purchased feature.
Socket.IO is the most popular WebSocket library for Node.js implementations. It handles automatic reconnection with configurable backoff, which is essential because Nigerian mobile networks frequently drop persistent TCP connections. Implement exponential backoff starting at 1 second and increasing to 30 seconds maximum, with a maximum of 20 reconnection attempts before falling back to a polling mechanism. For mobile apps, consider using native WebSocket implementations on Android and iOS for better battery performance compared to JavaScript-based libraries.
Firebase Cloud Messaging delivers push notifications to Android and iOS devices even when the app is backgrounded or closed. Register each users device token on your server during initial launch. When a payment webhook arrives, send an FCM message with title, body, and data payload for navigation. FCM delivery rates in Nigeria are 85% to 95% on Android and 95% to 98% on iOS. Run a weekly cleanup job to remove invalid tokens. For Chinese-brand phones without Google Play Services, consider an alternative push provider. For a comprehensive strategy, read our push notification strategy guide.
Even with push notifications, some messages will not reach the users device due to network issues, device settings, or app permissions. SMS is the most reliable fallback channel, working on every mobile phone in Nigeria regardless of smartphone type, operating system version, or network carrier. Use aggregators like Twilio, Termii, or BulkSMS with delivery rates above 95% and typical delivery times of 2 to 10 seconds. Keep SMS messages under 160 characters to avoid multi-part message charges, and include only essential information: transaction amount, reference number, and sender name.
The WhatsApp Business API offers rich notifications with action buttons for confirmations, such as view receipt, contact support, or rate your experience. This is particularly effective for non-urgent confirmations where user engagement adds value. Implement a clear channel priority system: push notification first because it is fastest and has zero per-message cost, SMS fallback triggered within 5 seconds if push delivery is not confirmed, and WhatsApp as a secondary confirmation sent 30 seconds later for a richer user experience with actionable buttons.
Your system must handle webhook retries safely through idempotency. Every webhook event includes a unique event ID. When your endpoint receives a webhook, extract this ID and check your database for an existing record. If the record exists, skip processing and return 200 OK. If not, process the event, store the ID with a unique constraint, and return 200 OK. This prevents duplicate credits, duplicate notifications, and other side effects. Log every webhook attempt including event ID, timestamp, HTTP status code, and processing result for CBN audit requirements.
Your notification system must handle every transaction status correctly to maintain user trust. A pending status means the transaction is awaiting confirmation from the payment provider and should not trigger a completion notification. A success status triggers push notification, SMS, and WebSocket update simultaneously for maximum delivery speed. A failed status sends a notification with the specific failure reason such as insufficient funds or declined by bank and offers a clear retry option directly in the notification. A reversed status, which occurs when a previously successful transaction is later reversed by the payment provider or issuing bank, must send an urgent SMS plus push alert to the user and immediately deduct the amount from the displayed account balance. If a transaction remains in pending status for over 5 minutes, send a notification reassuring the user that the transaction is still being processed and no action is needed on their part.
Webhooks are server-to-server callbacks notifying your backend of payment events. WebSocket provides persistent bidirectional connection for pushing updates to the users app in real time.
Paystack retries failed webhooks up to 7 times with exponential backoff. Your endpoint must be idempotent using the webhook event ID as the idempotency key.
Idempotency ensures processing the same webhook event multiple times does not cause duplicate transactions. Store processed event IDs in your database and skip duplicates.
Both. SMS works on all phones with near-100% delivery. WhatsApp offers rich notifications with action buttons. Use SMS for critical alerts, WhatsApp for confirmations.
