> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks & Webhooks

> Handle real-time payment notifications from Caibo payment providers and 3DS authentication

# Overview

Caibo IPG provides a comprehensive callback system to handle real-time payment status notifications from Caibo payment infrastructure and 3D Secure authentication. This ensures you receive immediate updates about payment status changes and authentication results. All callbacks are processed asynchronously and provide real-time updates.

## Supported Callbacks

### Caibo Payment Processing

#### Caibo Standard

* **Standard Callback**: `POST /callbacks/caibo`
* **Use Case**: Standard Caibo payment processing
* **Features**: Core payment method support

#### Caibo Gateway

* **Gateway Callback**: `POST /callbacks/caibo-gateway`
* **Use Case**: Advanced gateway payment processing
* **Features**: Enhanced payment routing and processing

#### Caibo Webhook

* **Webhook Callback**: `POST /callbacks/caibowh`
* **Use Case**: Dedicated webhook notifications
* **Features**: Real-time payment status updates

### Security & Authentication

#### 3D Secure

* **3DS Callback**: `POST /callbacks/3ds`
* **Purpose**: Handle 3D Secure authentication results
* **Security**: Enhanced transaction security

## Callback Implementation

### Setting Up Callbacks

1. **Configure Webhook URLs**: Set your notification URLs in payment requests
2. **Handle HTTP Methods**: Support both GET and POST methods as required
3. **Verify Signatures**: Validate callback authenticity using provider signatures
4. **Process Asynchronously**: Handle callbacks in background processes

### Common Callback Data

Most callbacks include:

* **Transaction ID**: Unique payment identifier
* **Status**: Payment status (success, failed, pending, etc.)
* **Amount**: Transaction amount and currency
* **Timestamp**: When the status change occurred
* **Provider Data**: Provider-specific information

### Response Requirements

* **HTTP 200**: Always return 200 OK for successful processing
* **Idempotency**: Handle duplicate callbacks gracefully
* **Timeout**: Respond within provider timeout limits (usually 10-30 seconds)
* **Retry Logic**: Providers will retry failed callbacks

## Testing Callbacks

### Test Environment

* **Test Callbacks**: `POST /callbacks/test/json`, `POST /callbacks/test/form`, `GET /callbacks/test/text`
* **Purpose**: Test your callback handling implementation
* **Formats**: Support for JSON, form data, and plain text

### Testing Strategy

1. **Unit Tests**: Test callback parsing and processing logic
2. **Integration Tests**: Test with actual Caibo test data
3. **Error Scenarios**: Test timeout, malformed data, and retry scenarios
4. **Load Testing**: Ensure callbacks can handle high volumes

## Error Handling

### Common Issues

* **Network Timeouts**: Implement proper timeout handling
* **Malformed Data**: Validate and sanitize callback data
* **Duplicate Callbacks**: Use idempotency keys to prevent duplicate processing
* **Provider Downtime**: Handle temporary provider unavailability

### Best Practices

1. **Logging**: Log all callback attempts for debugging
2. **Monitoring**: Monitor callback success rates and response times
3. **Alerting**: Set up alerts for callback failures
4. **Backup Processing**: Implement alternative status checking methods

## Security Considerations

### Callback Verification

* **IP Whitelisting**: Restrict callbacks to known Caibo provider IPs
* **Signature Validation**: Verify callback signatures when available
* **HTTPS Only**: Always use HTTPS for callback endpoints
* **Rate Limiting**: Implement rate limiting to prevent abuse

### Data Protection

* **Sensitive Data**: Never log sensitive payment information
* **Encryption**: Encrypt callback data in transit and at rest
* **Access Control**: Restrict access to callback processing systems

## Integration Examples

### Basic Callback Handler

```javascript theme={null}
app.post('/webhooks/payment-status', (req, res) => {
  try {
    const { transactionId, status, amount } = req.body;
    
    // Verify callback authenticity
    if (!verifySignature(req)) {
      return res.status(401).send('Unauthorized');
    }
    
    // Process payment status update
    await updatePaymentStatus(transactionId, status);
    
    // Always return 200 OK
    res.status(200).send('OK');
  } catch (error) {
    console.error('Callback processing error:', error);
    res.status(200).send('OK'); // Still return 200 to prevent retries
  }
});
```

### Callback Data Processing

```javascript theme={null}
function processCallback(provider, data) {
  switch (provider) {
    case 'caibo':
      return processCaiboCallback(data);
    case 'caibo-gateway':
      return processCaiboGatewayCallback(data);
    case 'caibowh':
      return processCaiboWebhookCallback(data);
    case '3ds':
      return process3dsCallback(data);
    default:
      throw new Error(`Unknown provider: ${provider}`);
  }
}
```

## Monitoring & Analytics

### Key Metrics

* **Callback Success Rate**: Percentage of successfully processed callbacks
* **Response Time**: Average callback processing time
* **Retry Rate**: Frequency of callback retries from providers
* **Error Rate**: Percentage of callback processing errors

### Troubleshooting

* **Failed Callbacks**: Check logs for processing errors
* **Missing Callbacks**: Verify webhook URL configuration
* **Delayed Callbacks**: Monitor provider-side delays
* **Duplicate Processing**: Implement proper idempotency checks

## Next Steps

<Card title="Payment Status Reference" icon="chart-line" href="/ipg/payment-requests/payment-status">
  Learn about querying payment status directly
</Card>

<Card title="Webhook Troubleshooting" icon="exclamation-triangle" href="/cpanel/troubleshooting/webhook-debugging">
  Debug webhook delivery and signature issues
</Card>

<Card title="Webhook Signatures" icon="shield-check" href="/cpanel/security/webhook-signatures">
  Verify and secure callback authenticity
</Card>