Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos en tu cuenta de Signatura. Por ejemplo, puedes configurar un webhook para recibir una notificación cada vez que un firmante haya firmado un documento.

De esta manera, no es necesario que estés consultando periódicamente el estado de los documento pendientes. Ten en cuenta que los firmantes pueden demorarse horas o incluso días en firmar un documento, o quizás abandonan el proceso. Si el conjunto de documentos pendientes crece sin límites, consumirás recursos innecesarios en tu aplicación y es posible que excedas los límites de la API de Signatura.

Para configurar un webhook, debes dirigirte a la sección de Webhooks de la Configuración de Cuenta. Puedes acceder a la configuración desde el menú de usuario ubicado en la esquina superior derecha. Asegurate de que la URL sea accesible, no esté protegida por un firewall y que responda con un código de estado 200.

Los webhooks de Signatura son enviados con el método POST y tienen un cuerpo en formato JSON. Consulta la referencia de la API para obtener más información sobre los eventos que puedes recibir.

Timeouts

Los webhooks de Signatura tienen un timeout de 5 segundos. Si tu servidor no responde con un código de estado 200 dentro de este tiempo, Signatura considerará que la notificación no fue entregada y reintentará el envío.

Política de reintentos

Los webhooks de Signatura siguen una política de reintentos en caso de que la URL de tu webhook no responda con un código de estado 200. La cantidad de reintentos está limitada y se realiza con un retraso exponencial. Si la URL de tu webhook no responde con un código de estado 200 después de varios reintentos, Signatura dejará de enviar notificaciones a esa URL.

info

Recuerda que los eventos pueden llegar en un orden diferente al que fueron generados. Asegúrate de que tu aplicación esté preparada para manejar eventos duplicados y fuera de orden.

Validación de firmas

Signatura Connect firma todos los webhooks utilizando HMAC-SHA256 con una clave simétrica. Esta firma te permite verificar que el webhook fue enviado por Signatura y que el contenido no fue modificado en tránsito.

La firma se incluye en el header X-Signature-SHA256 de cada solicitud. Para validarla, necesitas:

1. Obtener tu clave secreta desde la sección de Webhooks en la Configuración de Cuenta.
2. Decodificar la clave de hexadecimal a 32 bytes binarios.
3. Calcular el HMAC-SHA256 del cuerpo de la solicitud usando la clave decodificada.
4. Comparar el resultado con el valor del header X-Signature-SHA256.

Ejemplo en Python

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret_hex: str) -> bool:
    """
    Verifica la firma de un webhook de Signatura Connect.
    
    Args:
        payload: El cuerpo de la solicitud en bytes.
        signature: El valor del header X-Signature-SHA256.
        secret_hex: La clave secreta en formato hexadecimal (desde el panel).
    
    Returns:
        True si la firma es válida, False en caso contrario.
    """
    # Decodificar la clave de hex a bytes (32 bytes)
    secret_key = bytes.fromhex(secret_hex)
    
    # Calcular el HMAC-SHA256
    expected_signature = hmac.new(
        secret_key,
        payload,
        hashlib.sha256
    ).hexdigest()
    
    # Comparación segura para evitar ataques de timing
    return hmac.compare_digest(expected_signature, signature)


# Ejemplo de uso en un endpoint Flask
from flask import Flask, request, abort

app = Flask(__name__)

WEBHOOK_SECRET_HEX = "tu_clave_secreta_en_hex"

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Signature-SHA256")

    if not signature:
        abort(401, "Firma no proporcionada")

    if not verify_webhook_signature(request.data, signature, WEBHOOK_SECRET_HEX):
        abort(401, "Firma inválida")

    # Procesar el webhook
    event = request.json
    print(f"Evento recibido: {event}")
    
    return "OK", 200

aviso

Siempre valida la firma antes de procesar el contenido del webhook. Esto protege tu aplicación contra solicitudes falsificadas.

IPs de origen

Los webhooks de Signatura son enviados desde las siguientes direcciones IP:

• 3.229.233.201
• 54.75.193.230

Estas direcciones IP pueden cambiar en el futuro. Si tu implementación está detrás de un firewall, asegúrate de permitir el tráfico de estas direcciones IP y comunicarnos esto para que nos aseguremos de notificarte en caso de cambios.