Webhook security

There are three security mechanisms that we use to communicate data to your endpoint. These are:

1. HTTPS with TLS 1.2: You must ensure that the communication channel is secured with TLS 1.2

2. Encryption

   1. Payload encryption: We support UTF-8 for the encryption key. You should provide an encryption key of exactly 32 characters, compatible with the 256-bit key required by the AES-256-GCM encryption algorithm
   2. Payload decryption: The encrypted payload is stored in the body of the message as a stream of bytes. To decrypt, you will need the same encryption key that was used during the encryption process. As a result, we recommend that you store this key so that it can be used later for decryption
   3. Nonce and Authentication tag: Along with the encryption key, you will also need the Nonce and the Authentication Tag. These will be sent as Base64-strings as part of our HTTP Request header
   4. The decrypted payload is encoded as unicode/UTF-16LE

3. Data Integrity check
   To ensure the data received at your endpoint is the same as the data sent from our API, an SHA256-checksum will be sent as a Base64-string as one of the HttpRequest headers called Checksum. Through it, you can be sure the data you received from us hasn't been tampered with. To match the checksum of the header you need to re-encode the body to UTF8 before calculating the checksum. See the example below.

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} ");
}

Retry strategy

In cases where notifications cannot be successfully delivered to an endpoint, we will retry delivery with an exponential backoff with every failed delivery.

Your endpoint must respond with a 2xx HTTP status code to indicate successful receipt of the notification. After the 11th unsuccessful retry, we will stop sending notifications and deactivate the subscription.

The notification that caused the retries and other notifications that happened before the subscription deactivation are stored and they will be sent once the subscription is re-activated.

Any payment event that occur after the subscription is deactivated will not trigger any notifications.

📘

The rowVersion get updated at each retry attempt

It means that if a retry happens in between a GET and a PUT (for example whilst editing the endpoint url), the PUT will fail.

Failure notifications via email

You can associate an email address to a webhook subscription, allowing you to be notified via email if your endpoint returns something else than a 200 status code.

We will send two warning emails, followed by a final email notifying you that the subscription was deactivated. The table above shows when those emails are sent out.

Each email contains contains the subscription ID and the status code / error message we received during the last retry attempt.

Note that failure notifications via email is optional, and that this must be set up for each subscription. You can set the email either when setting up a subscription or updating an existing one.