Logo

Documentation v1.0.0

Webhook - Signature

Every notification we send to your endpoint is signed. We do this by including a header named "SmartFastPay-Signature" in every event we send. This allows you to verify and ensure that the event was sent by SmartFastPay and not a third party.

The "SmartFastPay-Signature" header contains a timestamp and one or more signatures. The timestamp is prefixed by t= and each signature is prefixed by a schema. Schemas start with v followed by an integer. Currently there is only one signature schema which is v1.

Exemplo do Header SmartFastPay-Signature:


SmartFastPay-Signature: t=1681235417000,v1=b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8

Signatures are generated using a hashed message based authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you must ignore all non-v1 schemas.

How to validate the signature

Step 1: Extract the Timestamp and Signature from the Header

Split the header using the character as a separator to get the list of elements. Once that's done, do another split using the = character as a separator, to get the prefix and the value.

The value obtained from the t prefix corresponds to the timestamp and the v1 corresponds to the signature. You can discard other values.

Step 2: Prepare the string to compare signatures

You must concatenate this information:

  • The timestamp (as string)
  • The character .
  • The JSON payload (request body, in string format)

Compute the HMAC with the SHA256 hash function. Use the secret (see what your secret is by clicking here ).

Example in PHP: 

                                                
                                                    // This secret is not the secret of the authentication token, it is the UID
                                                    $secret = 'my-secret';

                                                    // This is the "t" value received on SmartFastPay-Signature header
                                                    $timestamp = 1681235417000;

                                                    $requestPayload = [
                                                        'callback' => true,
                                                        'value' => 'value-field'
                                                    ];

                                                    $jsonPayload = json_encode($requestPayload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

                                                    $paramsSignature = "{$timestamp}.{$jsonPayload}";

                                                    echo hash_hmac('sha256', $paramsSignature, $secret);
                                                    // Output: b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8

Step 3: Compare signatures

Compare the signature sent by SmartFastPay in the Header with the signature you generated in Step 2.

Example in PHP: 

                                                
                                                    // Comparing Signatures
                                                    // Example Header of the request sent by SmartFastPay:
                                                    $headers = [
                                                        'SmartFastPay-Signature' => 't=1681235417000,v1=b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8'
                                                    ];

                                                    // Extract the value of 't' from Header 'SmartFastPay-Signature'
                                                    // '1681235417000'
                                                    $timestamp = explode("=", explode(",", $headers['SmartFastPay-Signature'])[0])[1];

                                                    // Extract the value of 'v1' from Header 'SmartFastPay-Signature'
                                                    // 'b9ffafcd16416bd11e36f877c2d7ccc71633d174f8245abc49fc2aef7e6633c8'
                                                    $signature = explode("=", explode(",", $headers['SmartFastPay-Signature'])[1])[1];

                                                    // The Signature you generated in Step 2 must be equal to the value of the "$signature" variable.
                                                    // Must return 1 (true)
                                                    echo ('yourSignature' === $signature);