Gateway Webhooks and Callbacks Setup

🔔 Introduction: What are Webhooks?

Webhooks are HTTP callbacks that a payment gateway sends to your server to notify you about payment events. They are the essential mechanism for automating order fulfillment, updating order statuses, and integrating payment confirmations into your application workflow.

Unlike polling (repeatedly calling the API to check status), webhooks provide real-time notifications and reduce API load. When a payment is confirmed, expired, or refunded, the gateway instantly sends a structured payload to your configured webhook URL.

📋 Step-by-Step Setup Guide

Step 1: Create Your Webhook Endpoint

Create an endpoint on your server that accepts POST requests. This is the URL where the gateway will send webhook notifications.

• URL format — https://yoursite.com/api/webhooks/payment
• Method — POST
• Content-Type — application/json (typically)
• Response — return HTTP 200 OK (2xx) to acknowledge receipt

Step 2: Configure Webhook in Gateway Dashboard

Log in to your payment gateway dashboard and navigate to the webhook configuration section:

• Endpoint URL — paste your server endpoint URL
• Event Selection — choose which events to subscribe to:

Step 3: Implement Signature Verification

To prevent forged webhook requests, most gateways sign webhook payloads with a secret key. Here's how to verify:

// Node.js example: Verify webhook signature
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(payload))
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

// In your webhook handler:
const payload = req.body;
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhook(payload, signature, WEBHOOK_SECRET);
if (!isValid) {
    return res.status(401).send('Invalid signature');
}
                    

Step 4: Handle Events

Process the webhook payload based on the event type:

// Example webhook handler
app.post('/webhooks/payment', (req, res) => {
    const event = req.body;
    switch (event.type) {
        case 'payment.confirmed':
            // Fulfill the order
            const orderId = event.data.order_id;
            updateOrderStatus(orderId, 'paid');
            sendConfirmationEmail(orderId);
            break;
        case 'payment.expired':
            // Cancel the order
            cancelOrder(event.data.order_id);
            break;
        case 'refund.completed':
            // Update refund status
            updateRefundStatus(event.data.refund_id, 'completed');
            break;
        default:
            // Log unknown event type
            console.log('Unhandled event:', event.type);
    }
    res.status(200).send('OK');
});
                    

Step 5: Test in Sandbox Environment

Before going live, test your webhook implementation in the gateway's sandbox environment:

• Simulate events — most gateways allow you to manually trigger webhook events from the dashboard.
• Check responses — verify that your endpoint returns 2xx status codes.
• Monitor logs — check your server logs to confirm payload receipt and processing.
• Test failure scenarios — simulate endpoint failure to verify gateway retry behavior.

🛡️ Webhook Security Best Practices

Implement these security measures to protect your webhook endpoint:

📊 Common Webhook Events

🔧 Troubleshooting Webhooks

Common issues and how to resolve them: