Recibe eventos de Bold a través de webhook

Crea el endpoint

Debes crear un endpoint que pueda aceptar peticiones HTTPS de tipo POST.

Este endpoint debe:

1. Recibir la solicitud POST con un cuerpo en formato JSON como el del 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 endpoint debe responder inmediatamente con el código de estado 200 antes de que cualquier lógica de tu sistema provoque un error por 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 de estructura de la notificación

Descripción del cuerpo de la notificación

Registra el endpoint

Después de crear el endpoint, registra la URL en la sección de Integraciones en el Panel de Comercios para que Bold sepa a dónde enviar los eventos.

Formato de la URL del webhook

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

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

Para registrar tu webhook debes:

1. Ve a la sección Integraciones en el Panel de Comercios. Si ingresas por primera vez debes activar las llaves de integración con el botón Activar llaves.

   Entre las llaves generadas encontratás la llave secreta. Esta sirve para verificar la autenticidad de la información enviada a la URL del webhook.

2. Luego de activar las llaves, ve a la sección Webhooks y haz clic en el botón Configurar webhook.

3. Agrega la URL del webhook en el campo URL de punto de conexión y haz clic en Crear webhook.

4. Ahora verás la URL 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.

5. Para dejar de recibir notificaciones en tu webhook configurado, simplemente elimínalo de tu lista de webhooks utilizando el botón de la papelera () ubicado en el lado derecho de la URL.

Las notificaciones de ventas realizadas mediante:

• Datáfono Bold Plus
• Link de pagos
• Botón de pagos
• Versiones antiguas de la app Bold

pueden tener una demora de máximo 10 minutos para que sean notificadas a tu webhook. Estamos trabajando para que estos tiempos sean menores.

Verifica el origen de los eventos recibidos

Te recomendamos asegurar tu integración de webhook con Bold. Para ello, es importante verificar que todas las peticiones realizadas a la URL del webhook sean generadas exclusivamente por Bold.

Cómo verificar las firmas de webhook

Para asegurar que la información provenga de Bold 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 secreta 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-bold-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
          pass
      else:
          # 400 status_code
          pass