Webhook for Payout

Overview

Receive real-time notifications for all Connected Banking payout transactions, eliminating the need for constant polling and ensuring immediate awareness of transaction status changes.

Key Features (Planned)

• Real-time Notifications: Instant payout status updates
• Comprehensive Data: Complete transaction details
• Reliable Delivery: Guaranteed webhook delivery
• Retry Mechanism: Automatic retry for failed deliveries
• Security Verification: HMAC signature verification
• Status Filtering: Configure which statuses trigger webhooks

Expected Webhook Configuration

Setup Method

Webhooks will be sent to the callback_url provided during payout initiation via the Connected Banking Payout API.

Required Field in Payout Request:

{
  "callback_url": "https://your-website.com/webhook/connected-banking-payout"
}

Expected Webhook Headers

Content-Type: application/json
User-Agent: Paywize-ConnectedBanking-Webhook/1.0
X-Paywize-Signature: sha256=signature_hash
X-Paywize-Event: payout_status_change
X-Paywize-Timestamp: 1640995200

Expected Webhook Payload

Encrypted Payload

{
  "data": "encrypted_payload_using_AES_256_CBC"
}

Decrypted Payload Structure

{
  "event_type": "payout_status_change",
  "transaction_id": "CBP123456789",
  "merchant_ref_id": "MERCHANT_TXN_001",
  "amount": "10000.00",
  "currency": "INR",
  "status": "COMPLETED",
  "status_message": "Payout completed successfully",
  "bank_reference": "BNK789456123",
  "beneficiary": {
    "account_number": "1234567890",
    "ifsc": "HDFC0001234",
    "account_holder_name": "John Doe",
    "bank_name": "HDFC Bank"
  },
  "payment_details": {
    "payment_mode": "OPEN_BANKING",
    "processing_time": "30",
    "charges": "5.00",
    "net_amount": "9995.00"
  },
  "timestamps": {
    "initiated_at": "2026-01-15T10:30:00Z",
    "completed_at": "2026-01-15T10:30:30Z",
    "webhook_sent_at": "2026-01-15T10:30:31Z"
  },
  "metadata": {
    "purpose": "salary_payment",
    "department": "engineering",
    "employee_id": "EMP001"
  }
}

Webhook Events

Status Change Events

• PROCESSING: Payout started processing
• COMPLETED: Payout successful
• FAILED: Payout failed
• CANCELLED: Payout cancelled
• REFUNDED: Payout amount refunded

Additional Events

• BANK_CONFIRMED: Bank confirmation received
• SETTLEMENT_INITIATED: Settlement process started
• COMPLIANCE_CHECK: Compliance verification complete

Expected Payload Fields

Security Verification

HMAC Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${computedSignature}` === signature;
}

// Usage
const isValid = verifyWebhookSignature(
  webhookPayload,
  request.headers['x-paywize-signature'],
  'your_webhook_secret'
);

Implementation Requirements

Endpoint Requirements

• HTTPS Only: Webhook URLs must use HTTPS
• Response Time: Respond within 30 seconds
• Response Code: Return 200 OK for successful processing
• Idempotency: Handle duplicate webhook deliveries

Error Handling

• Retry Logic: Handle temporary failures gracefully
• Status Codes: Return appropriate HTTP status codes
• Logging: Log all webhook receipts for debugging

Retry Mechanism

Retry Schedule

• 1st Retry: 30 seconds after failure
• 2nd Retry: 5 minutes after failure
• 3rd Retry: 30 minutes after failure
• 4th Retry: 2 hours after failure
• 5th Retry: 12 hours after failure

Failure Conditions

• HTTP Timeout: No response within 30 seconds
• HTTP Errors: 4xx or 5xx response codes
• Connection Errors: Network connectivity issues

Use Cases

Real-time Updates

• Status Dashboards: Live transaction monitoring
• Customer Notifications: Instant payment confirmations
• System Integration: Trigger downstream processes

Business Automation

• Workflow Triggers: Automate post-payment processes
• Reconciliation: Automatic payment matching
• Reporting: Real-time transaction reporting

Customer Experience

• Instant Confirmations: Immediate payment confirmations
• Status Updates: Real-time status communications
• Exception Handling: Quick failure notifications

Best Practices

Security

• Signature Verification: Always verify webhook signatures
• IP Whitelisting: Restrict webhook source IPs
• HTTPS Enforcement: Use HTTPS for all webhook URLs
• Secret Management: Secure webhook secret storage

Reliability

• Idempotency: Handle duplicate webhooks safely
• Error Handling: Implement proper error responses
• Logging: Comprehensive webhook logging
• Monitoring: Monitor webhook delivery success