Valida la firma de tu Webhook Endpoint

Al final de esta guía, podrás verificar que cada evento de webhook proviene de Fintoc revisando el header Fintoc-Signature. Fintoc firma cada evento enviado a tus webhook endpoints con el header Fintoc-Signature. Este header te permite verificar que cada evento recibido fue de hecho enviado por Fintoc y no por un tercero. Fintoc genera un secreto que se muestra solo una vez al momento del registro de un webhook endpoint. Este secreto es necesario para validar la firma de Fintoc de cada evento.

Verifica que los eventos sean enviados por Fintoc

Cada evento enviado por Fintoc incluye el header Fintoc-Signature. La estructura del header es la misma para cada evento. Contiene un timestamp denotado por la clave t y una firma denotada por la clave v1. Aquí hay un ejemplo de un header Fintoc-Signature:

t=1620870928,v1=4df951e02db34a3f333bccad26d207993e9b14d78ac77cec026091991f567f6d

Las firmas enviadas por Fintoc son simplemente códigos HMAC generados al firmar el cuerpo en bruto de la solicitud con la función hash SHA-256 en el momento indicado por el timestamp y usando el secreto del webhook endpoint. ¡Comencemos a validar la firma del evento!

Validar la firma usando nuestro SDK

Si estás usando Node o Python, verifica las firmas de los webhooks con nuestro SDK de Node o SDK de Python.

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

Para un ejemplo completo y funcional, revisa el código completo aquí.

Validar la firma usando tu propio código

Si quieres escribir tu propia implementación o usar un lenguaje de programación distinto, sigue estos pasos:

Extraer el timestamp y la firma del header

Divide el header Fintoc-Signature en un arreglo por el carácter ,. Luego, divide cada elemento del arreglo generado por el carácter = para obtener un par clave-valor. Finalmente, obtén los valores correspondientes para cada clave.

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

Reconstruir el mensaje firmado

El mensaje que Fintoc firmó antes de enviar el webhook corresponde al timestamp concatenado a un carácter . y al cuerpo en bruto de la solicitud. Reconstruyamos ese mismo mensaje usando el timestamp que acabamos de desempaquetar del header Fintoc-Signature y el cuerpo en bruto de la solicitud.

import json

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

Asegúrate de usar el cuerpo raw de la solicitud directamente desde la solicitud. Diferentes librerías pueden representar el JSON parseado de manera distinta. Un ejemplo del valor que message debería tener sería el siguiente:

'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"}'

Generar la firma

Ahora que tienes el mensaje que necesita ser firmado, hagamos justamente eso, usando la función hash SHA-256 y el secreto generado al crear el 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()

Comparar las firmas

Finalmente, comparemos la firma que desempaquetamos del header Fintoc-Signature con la que acabamos de obtener siguiendo los pasos de la guía. Si ambas firmas coinciden, entonces puedes asumir que el evento fue de hecho enviado por Fintoc.

import hmac

valid_signature = hmac.compare_digest(signature, event_signature)

Prevenir un ataque de replay

Para evitar un ataque de replay, define un rango de tolerancia aceptable para la antigüedad de los eventos. Al recibir un evento, compara el timestamp del header Fintoc-Signature con la hora actual. Usa cinco minutos como tolerancia por defecto. Acepta los eventos dentro de ese rango y descarta los que queden fuera.

Prueba la integración

Confirma que la validación de la firma funciona antes de depender de ella en producción. Genera un evento de prueba para tu webhook endpoint desde el Dashboard de Fintoc y revisa cómo responde tu handler:

Con una firma válida, tu handler valida el header y procesa el evento.
Con una firma inválida, por ejemplo un valor v1 modificado o el secreto incorrecto, tu handler rechaza el evento y retorna 400 Bad Request.

Inicio

Recursos

Pagos

Transferencias

Movimientos

Valida la firma de tu Webhook Endpoint

Verifica que los eventos sean enviados por Fintoc

Validar la firma usando nuestro SDK

Validar la firma usando tu propio código

Extraer el timestamp y la firma del header

Reconstruir el mensaje firmado

Generar la firma

Comparar las firmas

Prevenir un ataque de replay

Prueba la integración

​Verifica que los eventos sean enviados por Fintoc

​Validar la firma usando nuestro SDK

​Validar la firma usando tu propio código

​Extraer el timestamp y la firma del header

​Reconstruir el mensaje firmado

​Generar la firma

​Comparar las firmas

​Prevenir un ataque de replay

​Prueba la integración

Verifica que los eventos sean enviados por Fintoc

Validar la firma usando nuestro SDK

Validar la firma usando tu propio código

Extraer el timestamp y la firma del header

Reconstruir el mensaje firmado

Generar la firma

Comparar las firmas

Prevenir un ataque de replay

Prueba la integración