Webhook Setup for Merchants
Configure webhooks to receive real-time notifications about payment events. Essential for keeping your system synchronized with payment status changes.
Why Webhooks Matter
Webhooks allow you to receive instant notifications when payment events occur, eliminating the need to constantly poll the API for status updates.
- Real-time Updates: Know immediately when payments succeed or fail
- Automated Processing: Automatically update orders, send emails, or trigger other business logic
- Better UX: Provide instant feedback to customers about payment status
- Reduced Server Load: No need to poll the API repeatedly
Setting Up Webhooks
Configure webhooks through the merchant dashboard or API. You'll need a publicly accessible HTTPS endpoint to receive webhook events.
Step 1: Navigate to Webhooks
Go to Settings → Webhooks in your merchant dashboard
Step 2: Add Webhook URL
Enter your HTTPS endpoint URL (e.g., https://yourdomain.com/api/webhooks/payment)
Step 3: Select Events
Choose which events you want to receive (payment.succeeded, payment.failed, etc.)
Step 4: Save & Test
Save your webhook configuration and send a test event to verify it works
Webhook Security
Critical: Always Verify Signatures
Never process webhook events without verifying the signature. This prevents malicious actors from sending fake events to your endpoints.
Each webhook request includes an X-Altafinex-Signature header. Always verify this signature before processing events.
See our Webhook Guide for complete implementation examples.
Common Webhook Events
payment.succeededPayment completed successfully. Update order status, send confirmation email, fulfill the order.
payment.failedPayment was declined or failed. Notify the customer, allow retry, or suggest alternative payment method.
refund.completedRefund has been processed. Update your records and notify the customer.
Testing Webhooks
Use these tools to test your webhook endpoint during development:
- ngrok: Create a tunnel to your local server for testing
- webhook.site: Get a temporary webhook URL for testing
- Dashboard Test Button: Send a test event from the merchant dashboard
Best Practices
- Verify Signatures: Always verify webhook signatures before processing
- Idempotent Processing: Process events idempotently to handle duplicate deliveries
- Quick Response: Return 200 OK quickly, then process asynchronously
- Error Handling: Log errors but return 200 OK to prevent retries for permanent failures