Webhooks are a crucial component of the Fenan Pay system, allowing real-time notifications of transaction events to be sent directly to your server. This guide will walk you through the process of handling these webhook notifications securely and efficiently.

Webhooks are POST requests sent from Fenan Pay to your server, containing important transaction status updates.

​
Event Types

Fenan Pay sends different types of webhook events based on the transaction status:

​
Payment Events

  • payment_success
  • payment_failed
  • payment_expired

​
Withdrawal Events

  • withdrawal_success
  • withdrawal_failed

​
Webhook Payload Structure

The webhook payload contains a transaction event object with the following key components:

{
    "signature": "...",
    "body": {
        "event": "payment_success",
        ... // PaymentIntent or WithdrawalIntent object
    }
}
FieldTypeDescription
signaturestringA cryptographic signature to verify the payload’s authenticity.
bodyStringContains either a PaymentIntent or WithdrawalIntent Json string, depending on the event type. You need to parse this string to get the actual object.
eventstringSpecifies the type of webhook notification. which will be found inside the body object.

Always verify the webhook signature to ensure the body’s integrity and authenticity. Read more about verifying webhook signatures.

​
Example Webhook Events

​
Success Transaction

{
    "signature": "...",
    "body": {
        "event": "payment_success",
        ...// PaymentIntent object
    }
}

​
Success Withdrawal

{
    "signature": "...",
    "body": {
        "event": "withdrawal_success",
        ...// WithdrawalIntent object
    }
}

​
Acknowledging Webhooks

To properly acknowledge receipt of a webhook, your server must respond with:

​
Status Code
number

200

​
Content-Type
string

text/plain

​
Response Body
string

SUCCESS

Fenan Pay will retry the webhook up to 3 times at 2-minute intervals if not properly acknowledged.

​
Best Practices

  1. Verify signatures: Always verify the webhook signature before processing the payload.
  2. Process asynchronously: Handle webhook processing in the background to respond quickly.
  3. Idempotency: Design your webhook handler to be idempotent to safely handle potential duplicate events.
  4. Logging: Maintain detailed logs of received webhooks for troubleshooting and auditing.

​
Example Webhook Handler

Here’s a basic example of a webhook handler in Node.js:

const express = require('express');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const payload = req.body;
    const signature = req.headers['fenan-signature'];

    if (verifySignature(payload, signature, PUBLIC_KEY)) {
        // Process the webhook asynchronously
        processWebhookAsync(payload);
        
        // Acknowledge receipt
        res.status(200).contentType('text/plain').send('SUCCESS');
    } else {
        res.status(400).send('Invalid signature');
    }
});

async function processWebhookAsync(payload) {
    // Implement your webhook processing logic here
    console.log('Processing webhook:', payload.event);
    // Update your database, trigger notifications, etc.
}

​
Webhook Log

You can track how your server is handling webhooks in the Fenan Pay dashboard. This is very important for debugging and ensuring that your webhook processing is functioning correctly.

By following these guidelines, you’ll ensure robust and secure handling of Fenan Pay webhooks, keeping your system in sync with the latest transaction statuses.