Webhooks Overview
Receive real-time notifications when events happen in your EPaySe account
Webhooks allow you to build integrations that subscribe to events from EPaySe. When an event occurs, such as a successful payment, we send an HTTP POST request to your configured endpoint with event details.
Why Use Webhooks?
Webhooks provide significant advantages over polling for event updates
Real-time Notifications
Get notified instantly when payments succeed, fail, or require action
Reliable Delivery
Automatic retries with exponential backoff ensure delivery even if your server is temporarily unavailable
Efficient Integration
Process events asynchronously without blocking your checkout flow or polling our API
Quick Start
Get started with webhooks in 3 simple steps
Configure Endpoint
Create a webhook endpoint in your dashboard under Settings → Webhooks
Verify Signatures
Implement signature verification to ensure webhooks are authentic
Handle Events
Process events and return HTTP 200 to acknowledge receipt
Quick Start Example
// Your webhook endpoint
app.post('/webhooks/epayse', (req, res) => {
// 1. Verify signature (see Verification page)
const isValid = verifySignature(req);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// 2. Process the event
const event = req.body;
switch (event.type) {
case 'payment.succeeded':
// Fulfill the order
handlePaymentSuccess(event.data.object);
break;
case 'refund.completed':
// Update refund status
handleRefundComplete(event.data.object);
break;
// Handle other events...
}
// 3. Return 200 quickly
res.status(200).send('OK');
});Event Categories
Subscribe to the events that matter for your integration
Payment Events
Track payment lifecycle from creation to completion
payment.succeededpayment.failedpayment.processingRefund Events
Monitor refund requests and their outcomes
refund.createdrefund.completedrefund.failedDispute Events
Get notified when chargebacks are filed
dispute.createdConfiguration Limits
Configuration Limits
- Maximum 10 webhook endpoints per merchant
- HTTPS endpoint required (HTTP not supported)
- 30 second timeout per delivery attempt
- Up to 5 automatic retry attempts
Payload Structure
All webhooks follow a standardized format (API v2024-01-01)
{
"id": "evt_01HQKZ7N3BXYZ...",
"object": "event",
"type": "payment.succeeded",
"created": "2025-01-16T08:19:55Z",
"livemode": false,
"api_key_id": "client_01HQKZ...",
"data": {
"object": {
"id": "txn_01HQKZ...",
"object": "transaction",
"amount": 10000,
"currency": "USD",
"status": "SUCCESS",
"merchant_ref": "ORDER-2025-001"
}
},
"api_version": "2024-01-01"
}Best Practices
Return 200 Quickly
Respond with HTTP 200 within 30 seconds, then process the event asynchronously
Implement Idempotency
Use X-Webhook-Event-Id header to prevent duplicate processing
Always Verify Signatures
Never process webhooks without verifying the HMAC signature