Notifications from Flywire to you

When you register an application, you will receive a Shared Secret that you should use to validate the payload of the received notification. For more information about secure notifications see Validating Notifications.

Flywire supports notifications via callbacks (also known as webhooks). These allow your system to receive real-time notifications about important events.

Types of Callbacks

There are different types of callbacks:

Validating Notifications

Validating notifications is optional, as it’s on your server side, but for security reasons it is recommended to validate all notifications.

How to validate a notification

To validate a notification, check its X-Flywire-Digest header. This value is generated by Flywire using your Shared Secret to encrypt the notification body. To verify the notification, generate the digest using the same method and compare it to the X-Flywire-Digest value in the header. If they match, the notification is legitimate and hasn't been tampered with.

  1. Retrieve the raw HTTP body of the notification you received.

    Make sure you use the raw HTTP body of the notification. You must generate the X-Flywire-Digest value using the exact payload you received in the notification. If you change the body in any way the values won't match later.

 

  1. Encrypt the received notification twice:

    1) Encrypt the raw HTTP body of the received notification with your Shared Secret using the SHA-256 algorithm.

    2) Take the result and encrypt it in Base64.

    The examples show you how to do this in different programming languages. In each example, exchange the shared_key with your Shared Secret and message_body with the raw HTTP body of the notification.

    The Shared Secret is a string of characters used for security validations.

    For API integration:

    Your Shared Secret is used to validate notifications. You receive your Shared Secret together with your API credentials via a secure email after you registered your application.

    For other integrations:

    Your Shared Secret is used to validate notifications and authenticate requests. You receive your Shared Secret from the Flywire Solutions team after your portal has been set up (please contact the Solutions team in case you don't have your Shared Secret). Note that each portal might have a different shared secret. If you have access to multiple portals, make sure you use the correct shared secret for each portal.

    • Ruby
    • .NET
    • JavaScript 
    digest = OpenSSL::Digest.new('sha256')
encrypted_payload = OpenSSL::HMAC.digest(digest, shared_secret, notification_body)
Base64.encode64(encrypted_payload).strip
			
# Step 1: Define the hashing algorithm to use for the HMAC.
# This initializes the SHA-256 hashing mechanism.
hash_algorithm = OpenSSL::Digest.new('sha256')

# Step 2: Compute the HMAC in binary format.
# This uses the shared secret and the message body to produce the HMAC signature.
hmac_binary = OpenSSL::HMAC.digest(hash_algorithm, shared_secret, message_body)

# Step 3: Encode the HMAC in Base64 for use in the X-Flywire-Digest header.
x_flywire_digest = Base64.encode64(hmac_binary).strip
    public static string Digest(string shared_secret, string message_body)
{
    // Step 1: Initialize the HMACSHA256 object with the shared secret.
    // This sets up the hashing algorithm (SHA-256) and the secret key for HMAC.
    using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(shared_secret)))
    {
        // Step 2: Convert the message body into a byte array.
        // The message body is the message payload you want to hash
        var bytes = Encoding.UTF8.GetBytes(message_body);

        // Step 3: Compute the HMAC hash of the message body.
        // This generates the HMAC using the shared secret and the message body.
        var hashedBytes = hmacsha256.ComputeHash(bytes);

        // Step 4: Convert the hashed byte array into a Base64 string.
        return Convert.ToBase64String(hashedBytes);
    }
}
    const crypto = require('crypto');

function createDigest(shared_secret, message_body) {
    // Step 1: Initialize the HMAC with the SHA-256 algorithm and the shared secret.
    const hmac = crypto.createHmac('sha256', shared_secret);
    
    // Step 2: Update the HMAC with the message body.
    // The message body is the message payload you want to hash
    hmac.update(message_body);

    // Step 3: Get the HMAC digest and encode it in Base64.
    const digestHeader = hmac.digest('base64');
    
    return digestHeader;  // The `digestHeader` is the X-Flywire-Digest header.
}

     

  2. Compare your Base64 string to the value in the X-Flywire-Digest parameter of the notification you received.

    If the values match, the notification came from Flywire and hasn't been changed by a third party.

    If the values don't match, you shouldn't trust the notification.