Webhooks

Por qué usar webhooks

Puedes recibir eventos para ser notificado sobre las actualizaciones en tu integración en tiempo real. La pasarela de pago usa webhooks para este propósito. Webhook es un código que envía un objeto de evento a un endpoint cuando un objeto de API v.2 es modificado.

Para habilitar eventos de webhook, necesitas registrar endpoints de webhook, generar un secreto para firmar eventos, y seleccionar los eventos a escuchar. Puedes configurar estas opciones a través del Área personal.

Actualmente, puedes recibir los eventos relacionados con los siguientes objetos:

• Session
• Payment
• PaymentMethod
• Refund

Ver la lista completa de tipos de eventos soportados.

Descripción del evento

Cada evento es una petición POST con cuerpo JSON, con firma simétrica con HMAC.

Una sola petición de API podría resultar en la creación de múltiples eventos. Por ejemplo, si el intento de pago para una Session, creada dentro de la [integración redirect]((/integration/apiv2/structure/redirect-integration-apiv2.html), falla y no quedan más intentos de pago, recibes eventos session.completed, payment.failed y payment.canceled.

Estructura del encabezado del evento

Cada petición tiene los siguientes encabezados:

• X-Version - versión de API en formato YYYY-MM-DD (ejemplo: 2023-11-15);
• X-Signature – firma para webhook;
• API-Request-Id – identificador de petición (formato: req_UUID).

Ejemplo:

-H "Content-Type: application/json" \
-H "X-Signature: your_webhook_signature" \
-H "X-Version: 2023-11-15" \

Estructura del cuerpo del evento

El cuerpo del evento contiene los siguientes atributos:

Ejemplo del cuerpo del evento:

{
  "created": "2022-02-17T16:30:55+00:00",
  "data": {
    "object": {
      "id": "ps_2njmpfC9BUCfsmALYNEQv5eoR8SdVsEHuXZC7D3uLiRxqfb8g2wJzWo8UvE9QL",
      "amount": 90000,
      "created": "2022-02-17T16:10:54+00:00",
      "currency": "EUR",
      "expiresAt": "2022-02-17T16:10:54+00:00",
      "failureUrl": "https://mybestmerchantreturnurl.com/failure",
      "locale": "en",
      "paymentData": {
        "captureMethod": "automatic"
      },
      "paymentStatus": "unpaid",
      "paymentUrl": "https://dev.bpcbt.com/payment/merchants/ecom/payment.html?mdOrder=0fbfe391-c2d1-7528-a0a9-5a4500a99ded&language=en",
      "status": "expired",
      "successUrl": "https://mybestmerchantreturnurl.com/success"
    }
  },
  "type": "session.expired"
}

Tipos de eventos

Los siguientes tipos de eventos están soportados.

Versión de API

La versión de API será especificada en el encabezado X-Version del evento.

Por qué se generan objetos de evento

Los siguientes escenarios pueden activar la generación de objetos de evento:

• Cuando haces algunos cambios vía Área Personal (por ejemplo, hacer un reembolso)
• Cuando usas API
• Cuando un cliente hace algo vía la página de pago

Cómo configurar tu integración de webhook

Para comenzar a recibir eventos de webhook, crea y registra un endpoint de webhook siguiendo los pasos a continuación. Puedes registrar y crear uno o múltiples endpoints.

1. Identificar los eventos a monitorear

Usa la tabla de Tipos de eventos para identificar los eventos que quieres recibir.

2. Crear una función de endpoint de webhook

Configure una función de endpoint HTTPS que pueda aceptar solicitudes webhook con un método POST. Configure su función de endpoint para que:

• Maneje solicitudes POST con una carga JSON que consista en un objeto de evento.
• Devuelva rápidamente un código de estado exitoso (2xx) antes de cualquier lógica compleja que pueda causar un tiempo de espera agotado. Por ejemplo, debe devolver una respuesta 200 antes de actualizar la factura de un cliente como pagada en su sistema de contabilidad.

3. Registre su endpoint webhook a través del Área Personal

Puede configurar su integración webhook a través de su área Personal. Vea los detalles en la Guía del Usuario del Portal del Comerciante.

Cuando un webhook falla

Si se devuelve una respuesta distinta a 200 OK a la Pasarela de Pagos, el envío del evento se considera no exitoso. En este caso, la Pasarela de Pagos repite el envío del evento a intervalos de 30 segundos hasta que se cumple una de las siguientes condiciones:

• la Pasarela de Pagos recibe 200 OK,
• hay 3 fallas de webhook sucesivas.

Cuando se cumple una de las condiciones anteriores, los intentos de enviar un evento se detienen.

Mejores prácticas para usar webhooks

Solo escuche los tipos de eventos que su integración requiere

Configure sus endpoints webhook para recibir solo los tipos de eventos requeridos por su integración. Escuchar eventos adicionales (o todos los eventos) crea carga excesiva en su servidor, por lo que no lo recomendamos. Puede cambiar los eventos que un endpoint webhook recibe a través del área Personal.

Reciba eventos con un servidor HTTPS

Si usa una URL HTTPS para su endpoint webhook, la Pasarela de Pagos valida que la conexión a su servidor sea segura antes de enviar sus datos webhook. Para que esto funcione, su servidor debe estar configurado correctamente para soportar HTTPS con un certificado de servidor válido.

Verifique que los eventos sean enviados desde la Pasarela de Pagos

El encabezado X-Signature incluido en cada evento firmado contiene una marca de tiempo y una o más firmas que debe verificar. La marca de tiempo tiene el prefijo t=, y cada firma tiene el prefijo v1=. La Pasarela de Pagos genera firmas usando HMAC con SHA-256.

Ejemplo del encabezado X-Signature:

X-Signature: t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Para verificar la firma, siga estos pasos:

Paso 1: Extraiga la marca de tiempo y las firmas del encabezado

Divida el encabezado usando el carácter , como separador para obtener una lista de elementos. Luego divida cada elemento usando el carácter = como separador para obtener un par de prefijo y valor. El valor para el prefijo t corresponde a la marca de tiempo, y v1 corresponde a la firma (o firmas).

Paso 2: Prepare la cadena signed_payload

La cadena signed_payload se crea concatenando:

• La marca de tiempo (como una cadena)
• El carácter .
• La carga JSON real (es decir, el cuerpo del evento)

Paso 3: Determine la firma esperada

Calcule un HMAC con la función hash SHA256. Use el secreto de firma del endpoint como la clave y use la cadena signed_payload como el mensaje. El valor resultante será la firma esperada.

Paso 4: Compare las firmas

Compare la firma (o firmas) en el encabezado con la firma esperada. Para una coincidencia de igualdad, calcule la diferencia entre la marca de tiempo actual y la marca de tiempo recibida, luego decida si la diferencia está dentro de su tolerancia. Para proteger contra ataques de tiempo, use una comparación de cadenas de tiempo constante para comparar la firma esperada con cada una de las firmas recibidas.

Use soporte de dos secretos de firma

Muchas empresas requieren cambiar el secreto de firma de vez en cuando por propósitos de seguridad. Para hacer este cambio de forma segura, le recomendamos usar el siguiente enfoque:

1. Cuando vayas a cambiar tu secreto de firma, primero genera un nuevo secreto de firma manualmente o usando la herramienta de tu elección (el secreto debe ser una cadena aleatoria con al menos 20 símbolos - números y caracteres latinos).
2. Soporta dos secretos: 1) el viejo, 2) el nuevo que has generado.
3. Cambia el secreto viejo al nuevo secreto a través del Área Personal (ingrésalo en el campo Secreto de firma y haz clic en Guardar).
4. Asegúrate de que los eventos recibidos sean verificados correctamente por el nuevo secreto. Si algo sale mal, cambia el secreto de vuelta al viejo.
5. Si todo funciona correctamente, elimina el secreto viejo de tus sistemas.