Setting Up Webhooks for Real-Time Payment Notifications

Why Webhooks Matter

Webhooks provide real-time notifications when payment events occur. Unlike polling, webhooks push updates instantly, improving user experience and reducing server load.

Webhook Events

DGS-Pay sends webhooks for:

• payment.success - Payment completed successfully
• payment.failed - Payment was declined or failed
• disbursement.success - Transfer completed
• disbursement.failed - Transfer failed
• conversion.success - Currency conversion completed

Configuring Your Webhook URL

Set your webhook URL in the merchant dashboard under Settings → Webhook Settings. Alternatively, override per-request using the callback_url parameter.

Signature Verification

Every webhook includes an HMAC signature for verification. Always verify before processing:

$signature = $_SERVER['HTTP_X_DGS_SIGNATURE'];
$expected = hash_hmac('sha256', $payload, WEBHOOK_SECRET);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Unauthorized');
}

Best Practices

• Respond with HTTP 200 immediately
• Process events asynchronously
• Implement idempotency using dgs_reference
• Log all incoming webhooks
• Handle duplicates gracefully

Testing Webhooks

Use the merchant dashboard to resend failed webhooks or test your endpoint with sample payloads.