Events are important actions that occur within your FedaPay account, such as the creation of a transaction or an update to a customer. Understanding how these events work allows you to better manage your transactions and provide a better experience for your customers.Whenever an event occurs, FedaPay notifies you in real-time through event notifications. These notifications can be used to track and react to what is happening within your account, such as when a payment is approved or when a customer is updated.
Transactions on FedaPay follow a lifecycle, and each stage in this lifecycle generates a specific event. Here’s how it works:
Transaction Creation : Once the customer is created, you can assign a transaction to them. This triggers the transaction.created event.
Tracking Transactions: A transaction can evolve in several ways:
transaction.approved : The transaction has been approved, meaning the payment has been validated.
customer.created : When a new customer is added to your account, this generates the event
transaction.declined: The payment failed or was rejected.
transaction.canceled: The transaction was canceled before it was finalized.
transaction.transferred: The funds from the transaction have been transferred to the designated account (e.g., bank account or mobile money).
À chaque changement de statut, un nouvel événement est généré pour vous tenir informé. Par exemple, dès qu’une transaction est mise à jour, l’événement transaction.updated est déclenché.
Each event contains detailed information about what has just happened. You can view all these events in the Events section of your FedaPay dashboard, which gives you a complete history of all important actions in your account.
Track Payments: You are informed in real-time of the status of each transaction.
Manage Customers: You can track changes made to customer profiles.
Automate Processes: With event notifications, you can automate certain tasks on your site, like sending a confirmation email after a successful payment.
Webhooks are automatic notifications that FedaPay sends to your application or website when important events occur on your account. For example, you can receive a webhook when a transaction is successful or disputed.These notifications are particularly useful because they allow you to stay informed in real-time without having to manually check what is happening on your FedaPay account.
Each time an event occurs (e.g., an accepted payment), FedaPay creates an Event object. This object contains all relevant information about the event, such as the event type (successful payment) and associated details.Then, FedaPay sends this object to your chosen URL (called the endpoint) via an HTTP request. It is like FedaPay sending you a message to inform you of what has happened.
FedaPay sends webhooks from a predefined list of IP addresses.
Only trust events originating from these addresses.
2
Webhook Signature Verification
Each webhook is signed by FedaPay via the X-FEDAPAY-SIGNATURE header.
You can verify these signatures using:
Official FedaPay libraries.
Manual verification with your own solution.
3
How to Verify Webhook Signatures ?
Retrieve the Endpoint Secret
Go to Workbench → Webhooks Tab.
Select the endpoint and click Click to reveal.
FedaPay generates a unique secret key for each endpoint:
Different between test mode and live mode.
Unique for each used endpoint.
Signature Verification
When a Webhook is sent, FedaPay includes a signature in the request header.
This signature is present in the X-FEDAPAY-SIGNATURE header.
PTo verify that the message is authentic:
1- Use your Webhook secret key (retrievable from dashboard settings).
2- Use this key to verify the signature and ensure the Webhook is from FedaPay.
Tools for Signature Verification
To ensure that received Webhooks originate from FedaPay and have not been altered, it is essential to verify their signature.
FedaPay simplifies this process with its official libraries.
Here is an example of code showing how to verify the signature in a Node.js or PHP
Copy
const { Webhook } = require('fedapay')// You can find your endpoint's secret key in your webhook settingsconst endpointSecret = 'wh_sandbox...';// This example uses Express to receive webhooksconst app = require('express')();// Use body-parser to retrieve the raw body as a bufferconst bodyParser = require('body-parser');// Match the raw body to content type application/jsonapp.post('/webhook', bodyParser.raw({type: 'application/json'}), (request, response) => { const sig = request.headers['x-fedapay-signature']; let event; try { event = Webhook.constructEvent(request.body, sig, endpointSecret); } catch (err) { response.status(400).send(`Webhook Error: ${err.message}`); } // Handle the event switch (event.name) { case 'transaction.created': // Transaction créée break; case 'transaction.approved'': // Transaction approuvée break; case 'transaction.canceled'': // Transaction annulée break; default: console.log(`Unhandled event type ${event.type}`); } // Return a response to acknowledge receipt of the event response.json({received: true});});app.listen(4242, () => console.log('Running on port 4242'));
4
Prevent Replay Attacks
A replay attack consists of resending an intercepted webhook.
FedaPay includes a timestamp in the X-FEDAPAY-SIGNATURE header to prevent these attacks.
The timestamp is checked with the signature:
It cannot be modified without invalidating the signature.
If the timestamp is too old, your application can reject the webhook.
Each retry attempt (if the first one fails) generates a new signature and timestamp.
5
Respond Quickly with a 2xx Status
Your endpoint should respond quickly with a 2xx status before performing heavy processing.
Exemples :
Respond with 200 immediately.
Then, perform actions such as marking an invoice as paid.