Recibe eventos de Bold a través de tu endpoint de webhook

Crea el punto de conexión

Debes crear un punto de conexión HTTPS que pueda aceptar peticiones POST de webhook.

Este punto de conexión debe:

1. Recibir la solicitud POST con un cuerpo JSON como el siguiente ejemplo:

{
  "id": "191850cb-00f8-4f64-aa5f-4975848e9428",
  "type": "SALE_REJECTED",
  "subject": "CP332C3C9WZU",
  "source": "/payments",
  "spec_version": "1.0",
  "time": 1711989345347444700,
  "data": {
    "payment_id": "CP332C3C9WZU",
    "merchant_id": "CKKA859CGE",
    "created_at": "2024-04-01T11:35:42-05:00",
    "amount": {
      "total": 111111,
      "taxes": [
        {
          "base": 96618,
          "type": "VAT",
          "value": 4831
        }
      ],
      "tip": 9662
    },
    "card": {
      "capture_mode": "CHIP",
      "franchise": "VISA",
      "cardholder_name": "DARIO SUAREZ RUBEN",
      "terminal_id": "qpos_mini_27000230021050800072"
    },
    "user_id": "b7221e5b-aa8a-4c13-8105-8771a0088d35",
    "payment_method": "CARD",
    "metadata": {
      "reference": null
    }
  },
  "datacontenttype": "application/json"
}

2. El punto de conexión debe responder inmediatamente con el código de estado 200 antes de que cualquier lógica de tu sistema provoque un error de tiempo de espera (con un máximo de 2 segundos permitidos). Esta respuesta confirma que el evento fue recibido correctamente.

A continuación encontrarás la descripción de cada uno de los campos contenidos en el cuerpo del JSON

Descripción estructura notificación

Descripción cuerpo de la notificación

Registra el punto de conexión

Después de configurar tu punto de conexión, registra la URL del punto de conexión de webhook en la sección de Integraciones (opens in a new tab) en el panel de Comercios, para que Bold sepa a donde enviar los eventos.

Formato de la URL de tu endpoint

El formato de la URL para registrar tu webhook es el siguiente:

https://<tu-website>/<tu-webhook-endpoint>

Para registrar tu punto de conexión debes:

1. Ve a la sección Integraciones (opens in a new tab) en el panel de Comercios. si ingresas por primera vez debes activar las llaves de autenticación con el botón + Activar llaves.

   Estas llaves generadas (Llave de identidad) sirven para verificar la autenticidad de la información que es enviada a tu punto de conexión de webhook.

2. Luego de activar las llaves, ve a la sección Webhook, Haz clic en Configurar webhook

3. Agrega la URL HTTPS de tu punto de conexión de webhook en URL de punto de conexión y haz clic en Crear webhook.

4. Ahora verás el punto de conexión que acabas de configurar en la sección de webhooks creados, y podrás empezar a recibir automáticamente eventos de webhook cada vez que se realice una transacción.

Asegura tu integración webhook:

Te recomendamos asegurar tu integración del punto de conexión de webhook con Bold. Para lograrlo, es importante verificar que todas las peticiones de webhook sean generadas exclusivamente por Bold.

Cómo verificar las firmas de webhook:

Para asegurar que la información provenga de Bold (autenticidad) y garantizar la integridad de los datos, puedes seguir estos pasos:

1. Convertir el cuerpo recibido a formato Base64.

2. Cifrar el cuerpo en Base64 utilizando la Llave de identidad con el algoritmo de encriptación HMAC-SHA256 para generar un HMAC (código de autenticación de mensajes) en formato hexadecimal.

3. Comparar el resultado obtenido con el valor del encabezado X-Bold-Signature incluido en la petición y verificar que sean idénticos.

Ejemplo del contenido enviado en el header x-signature:

'x-bold-signature': '381db35c39c6e3016884c70054ade14f4d78bcd8167e8d1170751fe3bce74662'

A continuación encuentras un snippet que puedes utilizar para hacer la verificación de la firma:

  from flask import Flask, request
  import hmac
  import hashlib
  import base64
 
  app = Flask(**name**, instance_relative_config=False)
 
  @app.route("/", methods=["POST"])
  def validate_signature():
      signature = request.headers.get("x-bold-signature", "")
 
      body = request.get_data(parse_form_data=False)
 
      str_message = body.decode(encoding="utf-8")
 
      encoded = base64.b64encode(str_message.encode("utf-8"))
 
      hashed = hmac.new(key="<secret_key>".encode(), digestmod=hashlib.sha256, msg=encoded).hexdigest()
 
      is_valid_request = hmac.compare_digest(hashed.encode(), signature.encode())
 
      if is_valid_request:
        //200 response and process event
 
 
      //400 error response