Setting up Webhooks

Webhooks provide a secure and reliable way to receive real-time notifications about events in your account. This document outlines the technical requirements and security considerations for implementing webhook notifications.

Prerequisites

Successful webhook implementation requires several key components:

API Access

Webhook management requires appropriate API access permissions. Your API user must have the necessary permissions to manage webhook configurations and subscriptions.

Endpoint Requirements

Your webhook endpoint must be a secure HTTPS URL capable of handling various types of requests and data formats:

HTTP POST requests in JSON format
Binary stream processing (Content-Type: application/octet-stream)
IPv4 protocol support
Payload handling up to 50MB in size

Security Requirements

Security is paramount in webhook implementations. Your system must support:

AES-256-GCM encryption (requires a 32-character encryption key)
TLS 1.2 protocol
SHA256 checksum verification
Proper handling of encrypted payloads

Checksum Verification

To ensure data integrity, we send an SHA256 checksum as a Base64-encoded string in the HTTP request header. You must verify this checksum by:

Re-encoding the body to UTF8
Calculating the SHA256 hash
Comparing it with the received checksum

Here's an example of how to verify the checksum:

private void CalculateChecksum(string authTag, string nonce, string utf8AesKey, byte[] encryptedBody)
{
     var authTagInBytes = Convert.FromBase64String(authTag);
     var utf8AesKeyInBytes = Convert.FromBase64String(utf8AesKey);
     var nonceInBytes = Convert.FromBase64String(nonce);
 
     var decryptedBytes = AesGcmEncryptionService.Decrypt(encryptedBody, utf8AesKeyInBytes, nonceInBytes, authTagInBytes);
     var decryptedText = Encoding.Unicode.GetString(decryptedBytes);
 
     var contentHash = SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(decryptedText));
     var hash = Convert.ToBase64String(contentHash);
 
     Console.WriteLine($"Checksum is: {hash} ");
}

Network Configuration

IP Whitelisting

To maintain secure communication, your firewall must allow traffic from our IP addresses. This ensures that only authorized requests reach your endpoint.

Production Environment

51.104.183.88, 51.104.183.94, 51.104.183.101, 51.104.183.103, 51.104.183.106, 51.104.183.115, 51.104.183.229, 20.54.48.95, 20.54.48.105, 20.54.48.113, 20.54.48.122, 20.54.48.130, 20.67.184.104, 20.67.185.55, 20.67.185.96, 20.67.185.153, 20.67.185.206, 20.67.185.221, 20.67.185.228, 20.67.185.250, 20.67.186.42, 20.67.186.48, 20.67.186.50, 20.67.186.64, 20.54.48.159, 20.54.48.196, 20.54.48.210, 20.54.48.219, 20.54.48.241, 20.54.49.10, 20.50.64.12, 20.73.113.63, 20.76.58.170, 20.76.58.202, 20.76.59.51, 20.76.59.68, 20.76.59.96, 20.73.113.113, 20.76.59.149, 20.76.59.189, 20.76.59.236, 20.73.118.112, 20.76.56.90, 20.73.113.107, 20.76.60.207, 20.76.60.223, 20.76.61.55, 20.73.117.222, 20.76.61.195, 20.76.57.112, 20.73.116.227, 20.76.57.135, 20.76.61.202, 51.138.13.120, 51.138.97.100, 51.138.98.69, 51.124.151.146, 51.138.100.153, 51.138.101.10, 51.138.102.72, 20.50.154.139, 20.50.2.55, 20.157.111.19, 135.236.145.9, 135.236.144.255, 20.157.115.2, 135.236.66.216, 135.236.67.38

Sandbox Environment

20.67.201.6, 20.67.201.16, 20.67.201.23, 20.67.201.40, 20.67.201.48, 20.67.201.53, 20.67.201.72, 20.67.201.99, 20.67.201.117, 20.67.202.197, 20.67.202.200, 20.67.202.212, 20.67.202.220, 20.67.202.248, 20.67.203.10, 20.67.203.20, 20.67.203.26, 20.67.203.39, 20.67.203.47, 20.67.203.61, 20.67.203.66, 20.67.200.198, 20.67.200.210, 20.67.200.229, 20.67.200.248, 20.67.200.252, 20.67.201.3, 20.67.201.36, 20.67.201.50, 20.67.201.85, 20.50.64.11,52.156.253.199, 52.156.253.140, 135.236.114.55, 135.236.114.124

Security Implementation

Standard Security (TLS)

By default, webhook communications are secured using TLS. This ensures encrypted data transmission between Banking Circle and your endpoint. The implementation requires:

HTTPS with TLS 1.2 support
Proper handling of HTTP status codes
Robust error handling mechanisms

Mutual TLS (mTLS)

For organizations requiring enhanced security, mutual TLS authentication is available. This provides an additional layer of security through certificate-based authentication. Implementation of mTLS requires coordination with us for certificate exchange and configuration.

Response Requirements

Webhook endpoints must be designed to handle incoming notifications efficiently and securely:

Response time should be within 10 seconds to prevent timeout issues
HTTP status codes must be used appropriately:
- 2xx responses indicate successful receipt
- 4xx responses indicate client-side issues
- 5xx responses indicate server-side issues
Failed deliveries will trigger our retry mechanism