Using Webhooks to Build Real-Time Payment Dashboards

Why Webhooks Over Polling

The naive way to track payment status is to poll our API - make a GET request every few seconds to check if a transaction has completed. This is wasteful, introduces latency, and doesn't scale. MALIPOPAY webhooks push events to your server the moment they happen, typically within 200–500ms of a transaction completing.

Setting Up Your Webhook Endpoint

Your webhook endpoint is a simple HTTP server route that accepts POST requests from MALIPOPAY. It needs to do three things: verify the request signature, process the event, and return 200 quickly.

• Register your endpoint URL in Settings → Webhooks in your dashboard
• MALIPOPAY signs every webhook request with an HMAC-SHA256 signature using your webhook secret
• Always verify this signature before processing - this prevents spoofed webhook attacks
• Return 200 within 5 seconds; use a background job for heavy processing

Event Types

MALIPOPAY currently dispatches these event types to your webhook endpoint:

• transaction.completed - payment was successful
• transaction.failed - customer declined or timed out
• transaction.pending - awaiting customer confirmation
• disbursement.completed - outbound payout was successful
• settlement.completed - funds settled to your bank account

Building a Real-Time Dashboard

With webhooks delivering events, you can maintain a live transaction ledger in your own database and push updates to your frontend via Server-Sent Events or WebSockets.

A typical architecture: your webhook handler receives the event, writes it to your database, and publishes a message to a Redis Pub/Sub channel. Your frontend connects to a streaming endpoint that subscribes to that channel and pushes updates via SSE. Your dashboard updates in under a second of the customer completing payment.

This architecture gives you a live view of every transaction across all channels - mobile money, cards, bank transfers - in a single dashboard.

Handling Failures Gracefully

MALIPOPAY retries failed webhook deliveries with exponential backoff - up to 5 attempts over 24 hours. Make your handler idempotent (safe to call multiple times with the same event) by checking the transaction ID against your database before processing. Store the raw event payload for debugging; if a webhook fails to process, you can replay it from your logs.