WebHooks

En tu configuración de consumidor, tienes la opción de configurar una URL designada para recibir webhooks. Un webhook es una forma en que nuestro sistema envía notificaciones en tiempo real a tu sistema, alertándote sobre eventos a medida que ocurren.

La estructura de la carga útil del webhook es la siguiente:

{
  "event": "transfer_update",
  "timestamp": 1707298117,
  "data": {
    // Event-specific data here
  }
}

El campo event especifica el tipo de evento que activó el webhook. En este caso, transfer_update indica una actualización a una transferencia.

El campo data contiene información detallada relacionada con el evento, encapsulada dentro de un objeto. El contenido de este objeto variará dependiendo del evento específico que se esté notificando.

Eventos

transfer_update

Cuando una transferencia creada con estado pendiente es actualizada, confirmada o rechazada, se envía un webhook con el UUID de la transferencia y el nuevo STATUS:

Por ejemplo:

{
  "event": "transfer_update",
  "timestamp": 1707298117,
  "data": {
    "uuid": "4536d423-af81-4a93-9b1a-160ea6ca472b",
    "movementType": "DEPOSIT",
    "backStatus": "PENDING",
    "newStatus": "ACCEPTED"
  }
}

kyc_steep_update

Cuando se completa un paso de la sesión KYC, se notifica a través de un webhook.

Por ejemplo:

{
  "event": "kyc_steep_update",
  "timestamp": 1707298117,
  "data": {
    "session": "fd6260fd-6d23-4127-b161-3feba0c26a39",
    "steep": "GOVERNMENTAL_CHECK_SELFIE",
    "backStatus": "PENDING",
    "newStatus": "SUCCESS"
  }
}

Seguridad

Por motivos de seguridad, todos los webhooks están firmados utilizando JSON Web Signature (JWS). El cuerpo del webhook se envía firmado en formato JWS.

POST /webhook-endpoint HTTP/1.1
Host: example.com
Content-Type: plain/text

eyJhbGciOiJFUzI1NiIsImtpZCI6IjEyMzQ1In0K.ewogICJldmVudCI6ICJreWNfc3RlZXBfdXBkYXRlIiwKICAidGltZXN0YW1wIjogMTcwNzI5ODExNywKICAiZGF0YSI6IHsKICAgICJzZXNzaW9uIjogImZkNjI2MGZkLTZkMjMtNDEyNy1iMTYxLTNmZWJhMGMyNmEzOSIsCiAgICAic3RlZXAiOiAiR09WRVJOTUVOVEFMX0NIRUNLX1NFTEZJRSIsCiAgICAiYmFja1N0YXR1cyI6ICJQRU5ESU5HIiwKICAgICJuZXdTdGF0dXMiOiAiU1VDQ0VTUyIKICB9Cn0K%.cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7
AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4
BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K
0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqv
hJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrB
p0igcN_IoypGlUPQGe77Rw

El propósito de esta firma es asegurar la integridad y autenticidad del webhook, permitiendo que tu sistema verifique que el webhook fue efectivamente enviado por nuestro sistema y no ha sido alterado en el camino.

Para validar la firma del webhook, necesitarás utilizar la clave pública que te proporcionamos. Esta clave pública corresponde a la clave privada que usamos para firmar la carga útil del webhook. Al verificar la firma con la clave pública, puedes asegurarte de que el webhook es legítimo y procesar de manera segura la información contenida.

Por ejemplo:

JAVASCRIPT

const fs = require('fs');
const jwt = require('jsonwebtoken');
const publicKey = fs.readFileSync('./pubkey.pem');

jwt.verify(body, publicKey, [ algorithms: ['ES256'] ], function(err, decoded) {
  if (err) {
    console.error('Sign fail:', err.message);
  } else {
    console.log('Sign verified:', decoded);
  }
});

PYTHON

import jwt

public_key = '''...'''

try:
    decoded = jwt.decode(body, public_key, algorithms=['ES256'])
    print('Verified:', decoded)
except jwt.InvalidTokenError as e:
    print('Fail:', e)