🔔 Real-time Notifications

Webhooks

Receive real-time notifications about payment events and status changes.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur

Instead of polling the API to check payment status, webhooks automatically send HTTP POST requests to your server when events occur. This provides real-time updates and reduces API calls.

Example: When a payment is completed, PayFlow immediately sends a webhook to your server with the payment details, so you can update your database and notify your customer.

Webhook Events

Types of events that trigger webhooks

payment.succeeded

Payment was completed successfully

Triggers when payment status changes to COMPLETED

payment.failed

Payment processing failed

Triggers when payment status changes to FAILED

payment.cancelled

Payment was cancelled by customer

Triggers when payment status changes to CANCELLED

customer.created

New customer was created

Triggers when a new customer is added

Webhook Payload

Structure of webhook data sent to your endpoint

Each webhook contains event information and the associated data:

{
  "id": "evt_1234567890",
  "type": "payment.succeeded",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "pay_1234567890",
    "amount": 2500,
    "currency": "PKR",
    "status": "completed",
    "customer_email": "customer@example.com",
    "provider": "payfast",
    "provider_ref": "PF123456789"
  }
}

Event Fields

id - Unique event identifier
type - Event type (e.g., payment.succeeded)
created_at - When the event occurred
data - Event-specific data

Payment Data Fields

amount - Payment amount in smallest currency unit
currency - Three-letter currency code
status - Current payment status
provider_ref - Provider's reference number

Setting Up Webhooks

Configure webhook endpoints in your PayFlow dashboard

Step 1: Create Webhook Endpoint

Create a webhook endpoint in your application that can receive HTTP POST requests:

// Express.js example
app.post(&apos;/webhooks/payflow&apos;, (req, res) => {
  const event = req.body;
  
  // Handle the webhook event
  handleWebhookEvent(event);
  
  // Respond with 200 to acknowledge receipt
  res.json({ received: true });
});

Step 2: Configure in Dashboard

Go to Settings → Webhooks

Click "Add Webhook Endpoint"

Enter your webhook URL (must be HTTPS)

Select which events to receive

Save and test the webhook

Webhook Security

Protect your webhook endpoints from unauthorized access

Signature Verification

Always verify webhook signatures to ensure they come from PayFlow:

const crypto = require(&apos;crypto&apos;);

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac(&apos;sha256&apos;, secret)
    .update(JSON.stringify(payload))
    .digest(&apos;hex&apos;);
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

HTTPS Requirement

Webhook endpoints must use HTTPS to ensure data security. PayFlow will not send webhooks to HTTP endpoints.

Idempotency

Implement idempotency to handle duplicate webhook deliveries safely. Use the event ID to prevent processing the same event multiple times.

Testing Webhooks

Test your webhook implementation before going live

Webhook Testing Tool

Use the webhook testing tool in your PayFlow dashboard to send test webhooks to your endpoint:

Go to your webhook endpoint settings

Click "Send Test Webhook"

Check your endpoint receives the test event

Local Testing

For local development, use tools like ngrok to expose your local server to the internet:

# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the HTTPS URL provided by ngrok in your webhook endpoint

PayFlow Docs