This guide will walk you through the process of setting up webhooks in your Banked integration. You'll learn how to create a secure endpoint and configure it to receive real-time payment status updates and other important events.
Quick Start
To start receiving webhook events in your application:
- Create a webhook endpoint handler to receive event data POST requests
- Configure your webhook endpoint using the Banked API
Implementation Guide
1. Setting Up Your Webhook Endpoint
Here's an example of how to set up a webhook endpoint in Node.js to handle payment notifications:
javascript
const express = require('express');
const app = express();
// Parse JSON request bodies
app.use(express.json());
// Webhook endpoint
app.post('/webhooks/banked', async (req, res) => {
try {
// Verify the webhook signature
const signature = req.headers['banked-signature'];
// TODO: Implement signature verification
// Handle the webhook payload
const payload = req.body;
// Example: Handle a payment initiated event
if (payload.type === 'payment_initiated') {
console.log(`Payment ${payload.data.id} has been initiated`);
console.log(`Amount: ${payload.data.amount} ${payload.data.currency}`);
console.log(`Reference: ${payload.data.payment_identification.end_to_end_identification}`);
// TODO: Add your business logic here
// For example, update your database or trigger other processes
}
// Always return a 200 response to acknowledge receipt
res.status(200).send('Webhook received');
} catch (error) {
console.error('Error processing webhook:', error);
// Return 400 for invalid requests
res.status(400).send('Invalid webhook');
}
});
// Start the server
app.listen(3000, () => {
console.log('Webhook server listening on port 3000');
});
2. Configuring Webhooks via API
Create a Webhook
To create a webhook endpoint, make a POST request to the /v3/webhooks endpoint:
bash
curl --location --request POST 'https://api.banked.com/v3/webhooks' \
--header 'Authorization: Basic YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
"target_url": "https://your-domain.com/webhooks/banked",
"signature_key": "your-signature-key",
"version": "v3",
"events": [{"name": "payin_initiated"}]
}'
Request Parameters
| Parameter | Type | Description |
|---|---|---|
target_url | string | Your webhook endpoint URL (must be HTTPS) |
signature_key | string | Your signature key to verify webhook requests |
version | string | Default payload version for all events |
events | array | Array of event objects. Each object requires a name field (the event type) and an optional version field to override the default for that event |
Best Practices
1. Handle Duplicate Events
- Webhook endpoints might occasionally receive the same event more than once
- Log processed event IDs to prevent duplicate processing
- Use both the event ID and event type to identify duplicates
2. Process Events Asynchronously
- Use an asynchronous queue to process incoming events
- Avoid processing events synchronously to prevent scalability issues
- Handle concurrent events at a rate your system can support
3. Security Considerations
- Always use HTTPS in production
- Implement proper signature verification
- Exempt webhook routes from CSRF protection if using web frameworks
- Keep your webhook signing secrets secure and rotate them periodically
4. Response Handling
- Quickly return a 200 response before processing complex logic
- Implement proper error handling
- Use appropriate HTTP status codes (200 for success, 400 for invalid requests)