Getting Started With Webhooks

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 StartCopy URL

To start receiving webhook events in your application:

1. Create a webhook endpoint handler to receive event data POST requests
2. Configure your webhook endpoint using the Banked API

Implementation GuideCopy URL

1. Setting Up Your Webhook EndpointCopy URL

Here's an example of how to set up a webhook endpoint in Node.js to handle payment notifications:

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.webhook_event === 'payment_initiated') {
      console.log(`Payment ${payload.id} has been initiated`);
      console.log(`Amount: ${payload.amount} ${payload.currency}`);
      console.log(`Reference: ${payload.reference}`);

      // 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 APICopy URL

Create a WebhookCopy URL

To create a webhook endpoint, make a POST request to the /v2/webhooks endpoint:

curl -X POST https://api.banked.com/v2/webhooks \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-domain.com/webhooks/banked",
    "signature_key": "your-signature-key",
    "events": ["payment_initiated"]
  }'

Request ParametersCopy URL

Best PracticesCopy URL

1. Handle Duplicate EventsCopy URL

• 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 AsynchronouslyCopy URL

• 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 ConsiderationsCopy URL

• 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 HandlingCopy URL

• 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)