Webhooks | Noxipay — Professional Payment Solutions

What are Webhooks?

Webhooks allow you to receive real-time notifications when events occur in your Noxipay account. Instead of polling our API for updates, we'll send HTTP POST requests to your endpoint whenever something important happens.

Benefits

Real-time Updates

Get instant notifications when payments are completed, failed, or refunded

Reduce API Calls

No need to constantly poll our API for status updates

Automate Workflows

Trigger automated actions based on payment events

Available Events

Subscribe to these events to stay informed about your payments:

payment.completed

Triggered when a payment is successfully completed and funds are captured.

When: Customer completes payment
Data: Payment ID, amount, customer info

payment.failed

Triggered when a payment attempt fails due to various reasons.

When: Payment fails
Data: Payment ID, failure reason, error details

refund.completed

Triggered when a refund is successfully processed.

When: Refund is completed
Data: Refund ID, original payment ID, amount

chargeback.created

Triggered when a chargeback is filed against one of your payments.

When: Chargeback is filed
Data: Chargeback ID, payment ID, reason

Setting Up Webhooks

Configure your webhook endpoints in a few simple steps:

1. Create Endpoint

Set up a secure HTTPS endpoint on your server to receive webhook notifications.

                            Example Endpoint
                        
                            POST https://yoursite.com/webhooks/noxipay
Content-Type: application/json
X-Noxipay-Signature: sha256=...

2. Configure in Dashboard

Add your webhook URL and select which events you want to receive:

URL: https://yoursite.com/webhooks/noxipay
Events: payment.completed, payment.failed, refund.completed
Secret: Generate a webhook secret for verification

3. Verify Signatures

Always verify webhook signatures to ensure the request comes from Noxipay.

                            PHP Example
                        

                            <?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_NOXIPAY_SIGNATURE'];
$secret = 'your_webhook_secret';

$expectedSignature = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(400);
    exit('Invalid signature');
}

// Process webhook
$data = json_decode($payload, true);
// Handle the event...
                        

Webhook Payload

Understand the structure of webhook notifications:

Example Payload

                            Payment Completed Webhook
                        

                            {
  "id": "evt_1234567890",
  "type": "payment.completed",
  "created": "2024-01-15T10:35:00Z",
  "data": {
    "id": "pay_1234567890",
    "status": "completed",
    "amount": 2500,
    "currency": "EUR",
    "description": "Payment for order #123",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "payment_method": {
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "4242"
      }
    },
    "metadata": {
      "order_id": "123",
      "customer_id": "cust_456"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z"
  }
}
                        

Payload Fields

Webhook Object

id - Unique webhook event ID
type - Event type (e.g., payment.completed)
created - Timestamp when webhook was sent
data - Event-specific data object

Payment Object

id - Payment ID
status - Payment status
amount - Amount in cents
currency - Currency code
description - Payment description
customer - Customer information
metadata - Custom metadata

Best Practices

Follow these guidelines for reliable webhook handling:

🔒 Verify Signatures

Always verify webhook signatures using your webhook secret to ensure authenticity

🔄 Handle Retries

Return 2xx status codes for successful processing. We'll retry failed deliveries

⏱️ Process Quickly

Process webhooks within 30 seconds to avoid timeouts and retries

💾 Store Events

Store webhook events in your database for audit trails and debugging

🔁 Handle Duplicates

Use webhook event IDs to prevent duplicate processing of the same event

🌐 Use HTTPS

Always use HTTPS endpoints to protect webhook data in transit

Testing Webhooks

Test your webhook implementation before going live:

Test Mode

Use test mode to send webhooks to your development environment without affecting live data.

                            Test Webhook URL
                        
                            https://yoursite.com/webhooks/noxipay/test

Webhook Logs

Monitor webhook delivery attempts and responses in your Noxipay dashboard. You'll see entries like:

2024-01-15 10:35:00 - 200 OK - payment.completed
2024-01-15 10:34:30 - 500 Error - payment.failed

Next Steps

API Keys

Learn how to manage your API keys

JavaScript SDK

Get started with our JavaScript SDK