Webhooks Guide
Receive real-time payment notifications
What are Webhooks?
Webhooks allow CasPay to send real-time notifications to your server when events occur, such as successful payments or subscription updates.
Setting Up Webhooks
const webhook = await caspay.webhooks.create({ url: 'https://yourdomain.com/webhook', events: [ 'payment.completed', 'payment.failed', 'subscription.created', 'subscription.canceled' ], secret: 'your_webhook_secret' });
Available Events
Payment Events
Payment successfully completed
Payment failed or rejected
Payment is being processed
Subscription Events
New subscription created
Subscription details updated
Subscription canceled
Recurring payment succeeded
Recurring payment failed
Webhook Payload Example
{ "id": "evt_123", "type": "payment.completed", "created": 1640000000, "data": { "payment": { "id": "pay_123", "amount": 100000000000, "currency": "CSPR", "status": "completed", "metadata": { "orderId": "order_456" } } } }
Verifying Webhook Signatures
import crypto from 'crypto'; function verifyWebhook(payload, signature, secret) { const hmac = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return hmac === signature; } // In your webhook handler app.post('/webhook', (req, res) => { const signature = req.headers['x-caspay-signature']; const isValid = verifyWebhook( JSON.stringify(req.body), signature, process.env.WEBHOOK_SECRET ); if (!isValid) { return res.status(401).send('Invalid signature'); } // Process webhook... res.status(200).send('OK'); });
Best Practices
Verify Signatures
Always validate webhook signatures before processing
Respond Quickly
Return 200 OK within 5 seconds to avoid retries
Handle Idempotency
Use event IDs to prevent duplicate processing
Test Thoroughly
Use test mode webhooks before going live