Troubleshooting Webhooks

This guide covers common issues you might encounter when working with webhooks and how to resolve them.

Not Receiving Notifications

If you're not receiving webhook notifications, check the following:

1. Subscription Status

   • Use the GET /api/v1/notificationselfservice/subscription endpoint to verify if your subscription is active
   • Check if the subscription has been deactivated due to repeated failures

2. Network Configuration

   • Verify that your firewall allows incoming connections from BC Connect IPs
   • Ensure all required IPs are whitelisted (see Setting up Webhooks)
   • Check if your endpoint is accessible from the internet

3. Endpoint Configuration

   • Verify the URL is correct and accessible
   • Ensure the endpoint is secured with a valid SSL certificate
   • Confirm the endpoint can handle binary streams
   • Check that your endpoint responds with a 2xx status code

Data Issues

If you're receiving notifications but having trouble with the data:

1. Decryption Problems
   • Verify the encryption key is exactly 32 characters
   • Ensure you're using the correct nonce and authentication tag from the headers
   • Something might be wrong with your decryption code. Here are examples in Java and .NET of how the message can be decrypted:

// Java example
private static final String ALGORITHM = "AES";
private static final Charset DEFAULT_CHARSET = StandardCharsets.UTF_8;
private static final String ALGORITHM_CIPHER_TYPE = "AES/GCM/NoPadding";

private static Cipher initCipher(byte[] key, byte[] iv, int tagLength, int mode) throws Exception {
    SecretKeySpec secretKeySpec = new SecretKeySpec(key, ALGORITHM);
    GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(tagLength, iv);
    Cipher cipher = Cipher.getInstance(ALGORITHM_CIPHER_TYPE);
    cipher.init(mode, secretKeySpec, gcmParameterSpec);
    return cipher;
}

// .NET example
public static byte[] Decrypt(byte[] encryptedBytes, byte[] aesKey, byte[] aesNonce, byte[] authenticationTag)
{
    using var aesGcm = new AesGcm(aesKey);
    var decryptedTextBytes = new byte[encryptedBytes.Length];
    aesGcm.Decrypt(aesNonce, encryptedBytes, authenticationTag, decryptedTextBytes, null);
    return decryptedTextBytes;
}

2. Data Integrity
   • Verify the checksum matches the decrypted payload
   • Ensure you're using UTF-8 encoding when calculating the checksum
   • Check that the payload hasn't been modified during transmission