Validate webhook signatures

By the end of this guide, you can verify that every webhook event came from Fintoc by checking the Fintoc-Signature header. Fintoc signs every event sent to your webhook endpoints. The Fintoc-Signature header lets you verify that Fintoc, not a third party, sent each event. Fintoc generates a secret when you register a webhook endpoint. You need this secret to validate the Fintoc signature of every event.

Verify that Fintoc sent the event

Each event sent by Fintoc includes the Fintoc-Signature header. The header contains a Unix timestamp in t and a signature in v1. For example:

t=1620870928,v1=4df951e02db34a3f333bccad26d207993e9b14d78ac77cec026091991f567f6d

Each signature is a hash-based message authentication code. Fintoc uses SHA-256 to generate the signature from the raw request body and timestamp. The signature uses your webhook endpoint secret.

Validate the signature with the Fintoc SDKs

If you use Node or Python, verify webhook signatures with the Fintoc Node SDK or Fintoc Python SDK.

const { WebhookSignature, WebhookSignatureError } = require('fintoc');

// Use the secret returned when you created the endpoint
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// Rest of your code here
// ...

// express.raw keeps req.body as the raw Buffer, which the signature covers.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body;

  // Get the signature header
  const signature = req.headers['fintoc-signature'];

  try {
    // Verify the webhook signature
    WebhookSignature.verifyHeader(
      payload,
      signature,
      WEBHOOK_SECRET
    );

    // If verification passes, process the webhook
    const event = JSON.parse(payload.toString());

    // Rest of your code...

    // Acknowledge receipt of the event
    res.status(200).json({ received: true });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      console.error('Webhook signature verification failed');
      res.status(400).json({
        error: 'Invalid signature',
        message: error.message
      });
    } else {
      res.status(500).json({ error: 'Webhook handler failed' });
    }
  }
});

import os

from fintoc.webhook import WebhookSignature
from fintoc.errors import WebhookSignatureError

WEBHOOK_SECRET = os.getenv('FINTOC_WEBHOOK_SECRET')

# Rest of your code
# ...

@app.route('/webhook', methods=['POST'])
def handle_webhook():
  # Get the signature header
  signature = request.headers.get('Fintoc-Signature')

  # Get the raw request payload
  payload = request.get_data().decode('utf-8')

  # Verify the webhook signature
  try:
    WebhookSignature.verify_header(
      payload=payload,
      header=signature,
      secret=WEBHOOK_SECRET
    )

  except WebhookSignatureError as e:
    print('Invalid signature!')
    return str(e), 400

  # Acknowledge receipt of the event
  return '', 200

For a complete implementation, see the Python webhook example.

Validate the signature with your own code

If you want to write your own implementation or use a different programming language, follow these steps:

Extract the timestamp and the signature

Split the Fintoc-Signature header at each , character. Then, split each array element at the = character to obtain a key-value pair. Get the corresponding value for each key.

# Use the Flask request.
header_value = request.headers.get('Fintoc-Signature')
timestamp, event_signature = [x.split('=')[1] for x in header_value.split(',')]

Rebuild the signed message

The signed message consists of the timestamp, a . character, and the raw request body. Rebuild the message with the timestamp from the Fintoc-Signature header.

import json

# Use the Flask request.
message = f"{timestamp}.{request.get_data().decode('utf-8')}"

Use the raw, unparsed request body. Libraries can represent parsed JSON differently. For example, message should look like this:

'1626102791.{"id":"evt_DyzYBwdC07ao5MqG","type":"link.credentials_changed","mode":"test","created_at":"2021-07-12T15:11:09.875Z","data":{"id":"link_00000000","mode":"test","active":true,"object":"link","status":"active","accounts":null,"username":"111111111","holder_id":"111111111","created_at":"2021-06-24T00:00:00.000Z","link_token":null,"holder_type":"individual","institution":{"id":"cl_banco_bbva","name":"Banco BBVA","country":"cl"}},"object":"event"}'

Generate the signature

Generate the signature with SHA-256 and the secret returned when you created the webhook endpoint.

import hmac
from hashlib import sha256

# The secret returned when you created the webhook endpoint
YOUR_WEBHOOK_SECRET = 'YOUR_WEBHOOK_SECRET'
encoded_secret = YOUR_WEBHOOK_SECRET.encode('utf-8')
encoded_message = message.encode('utf-8')
hmac_object = hmac.new(encoded_secret, msg=encoded_message, digestmod=sha256)
signature = hmac_object.hexdigest()

Compare the signatures

Compare the signature from the Fintoc-Signature header with the signature you generated. If both signatures match, the event came from Fintoc.

import hmac

valid_signature = hmac.compare_digest(signature, event_signature)

Prevent a replay attack

To prevent a replay attack, define an acceptable age for events. When you receive an event, compare the timestamp from the Fintoc-Signature header with the current time. Use five minutes as the default tolerance. Accept events within this range, and discard events outside it.

Test the integration

Confirm that signature validation works before you rely on it in production. Trigger a test event for your webhook endpoint from the Fintoc Dashboard, then check how your handler responds:

With a valid signature, your handler validates the header and processes the event.
With an invalid signature, such as a modified v1 value or the wrong secret, your handler rejects the event and returns 400 Bad Request.

Home

Resources

Payments

Transfers

Movements

Validate webhook signatures

Verify that Fintoc sent the event

Validate the signature with the Fintoc SDKs

Validate the signature with your own code

Extract the timestamp and the signature

Rebuild the signed message

Generate the signature

Compare the signatures

Prevent a replay attack

Test the integration

​Verify that Fintoc sent the event

​Validate the signature with the Fintoc SDKs

​Validate the signature with your own code

​Extract the timestamp and the signature

​Rebuild the signed message

​Generate the signature

​Compare the signatures

​Prevent a replay attack

​Test the integration

Verify that Fintoc sent the event

Validate the signature with the Fintoc SDKs

Validate the signature with your own code

Extract the timestamp and the signature

Rebuild the signed message

Generate the signature

Compare the signatures

Prevent a replay attack

Test the integration