Overview
Webhooks provide real-time notifications about transaction status changes, eliminating the need for polling. When a transaction completes, fails, or changes status, FundKit sends an HTTP POST request to your configured endpoint with the updated information.Webhooks are optional. You can poll for transaction status using
getTransaction(), or
configure webhooks for real-time updates. Webhooks are recommended for production but not required
for sandbox testing.Why Use Webhooks?
Real-time Updates
Get notified instantly when transactions complete, fail, or change status
Reduced API Calls
No need to poll for status updates - webhooks push updates to you
Better Performance
Lower latency and reduced server load compared to polling
Reliable Delivery
Built-in retry mechanisms ensure webhook delivery
Webhook Flow
1
Configure Webhook URL
Set your webhook endpoint URL and secret in PaymentClient configuration
2
Transaction Event Occurs
Payment completes, fails, or status changes
3
Webhook Sent
FundKit sends HTTP POST to your endpoint with event data
4
Verify & Process
Your server verifies signature and processes the event
5
Respond with 200
Acknowledge receipt with HTTP 200 status code
Configuration
PaymentClient-Level Configuration
Webhooks are configured at thePaymentClient level, not at the provider level. This provides a unified webhook endpoint for all providers:
All providers will use the same webhook endpoint configured in
PaymentClient. The webhook
payload will include a provider field to identify which provider processed the transaction.Production Webhook Setup
When moving to production, you need to configure webhooks in your FundKit dashboard and each provider’s dashboard. This setup is only required for production - sandbox mode works without webhook configuration.Video Tutorial
Watch this step-by-step guide on how to activate and use webhooks in the FundKit dashboard:1
Navigate to Provider Webhooks
Go to your app dashboard → Providers tab → Provider Webhooks section

2
Activate Webhooks
Toggle on the webhook for each provider you’re using (HoneyCoin, EasyPay, Tola, Tingg, etc.) The
webhook will show as Active (purple toggle) when enabled.
3
Copy Webhook URLs
Click the Copy button next to each provider’s webhook URL to copy it to your clipboard
4
Configure in Provider Dashboard
Paste the webhook URL into the corresponding provider’s dashboard: - HoneyCoin: Dashboard →
Settings → Webhooks - EasyPay: Dashboard → Integration → Webhooks - Tola: Dashboard →
Configuration → Webhooks - Tingg: Dashboard → Settings → Webhook Configuration - And so on
for other providers
Note: - Webhook configuration is only required for production. In sandbox mode, you can
test transactions without webhooks by polling for status using
getTransaction(). - The webhook
URL in your FundKit dashboard is automatically generated and unique to your app. - You must
activate and configure webhooks for each provider you plan to use in production.Webhook Events
Common Event Types
transaction_completed
transaction_completed
Triggered when: Payment is successfully completedTypical timing: 30 seconds to 5 minutes after initiationAction required: Update order status, fulfill service, send confirmation
transaction_failed
transaction_failed
Triggered when: Payment fails for any reasonTypical timing: Immediately to 5 minutes after initiationAction required: Update order status, notify customer, log for analysis
transaction_pending
transaction_pending
Triggered when: Payment is initiated and waiting for customer actionTypical timing: Immediately after payment initiationAction required: Show pending status to customer
Webhook Event Structure
All webhook events follow this structure:transaction_completed- Payment successfully completedtransaction_failed- Payment failedtransaction_pending- Payment initiated and waiting for customer action
transactionId- Unique transaction identifiertransactionType- Type of transaction (COLLECTION or PAYOUT)amount- Transaction amount as a string (in smallest currency unit)currency- Currency code (e.g., UGX, KES, TZS)operator- Mobile money operator (e.g., mtn, airtel, mpesa)accountNumber- Customer account/phone numberexternalId- Your external reference IDenvironment- Environment where transaction occurred (sandbox or production)
Testing Webhooks
Local Development with ngrok
Set up local webhook testing:1
Install ngrok
2
Start Your Local Server
3
Expose with ngrok
https://abc123.ngrok.io)4
Configure Webhook URL
Webhook Testing Utility
Troubleshooting
Webhooks Not Being Received
Webhooks Not Being Received
Possible causes:
- Webhook URL not configured correctly
- Server not accessible from internet
- Firewall blocking webhook provider IPs
- Verify webhook URL in provider dashboard
- Test endpoint with curl or webhook testing tools
- Check firewall and security group settings
- Use ngrok for local development testing
Signature Verification Failing
Signature Verification Failing
Possible causes:
- Wrong webhook secret
- Body parsing modifying payload
- Incorrect signature calculation
- Verify webhook secret in environment variables
- Use raw body parser for webhook endpoints
- Log received vs expected signatures for debugging
- Check timestamp validation logic
Duplicate Webhooks
Duplicate Webhooks
Possible causes:
- Webhook endpoint returning non-200 status
- Processing taking too long
- Network timeouts
- Always return 200 for successfully received webhooks
- Implement idempotency using event IDs
- Process webhooks asynchronously
- Respond quickly (< 5 seconds)
Missing Webhooks
Missing Webhooks
Possible causes:
- Provider service issues
- Webhook URL changed
- Rate limiting
- Check provider status pages
- Verify webhook configuration
- Implement webhook retry/recovery mechanisms
- Use transaction status polling as backup