Configurar webhooks

Te contamos cómo usar nuestros webhooks para recibir notificaciones en tiempo real.

En Pomelo usamos webhooks para informarte sobre los principales eventos que afectan a tu operación:

• Cuando se inicia una transacción de pago (CARDS)
• Si se realiza un ajuste sobre una transacción existente (CARDS)
• Cuando se resuelve el estado de una transacción (CARDS)
• Cada vez que modifica el estado de un envío(CARDS)
• Cuando se crea o actualiza una actividad (DIGITAL ACCOUNTS)
• Cuando se valida la identidad de un usuario (IDENTITY)

Cada vez que suceden esos eventos, hacemos una solicitud POST a un endpoint HTTPS en tu servidor usando un objeto JSON con la información.

Cómo configurar un webhook

Paso 1: Crear tu endpoint

Debes crear un endpoint en tu servidor que cumpla estos requisitos:

• Recibir tráfico por HTTPS
• Recibir un objeto JSON en el cuerpo de la solicitud

Paso 2: Reconocer nuestras IPs

Siempre nos comunicamos desde IPs específicas propias. Te recomendamos que solo aceptes solicitudes de alguna de nuestras IPs y que rechaces cualquier otra dirección.

• Ambiente de Testing/Staging:
  34.226.254.178
  44.198.3.59
  34.223.185.46
  100.20.205.117
  

• Ambiente de Producción:
  34.206.159.176
  52.0.20.124
  35.84.78.117
  52.43.46.111
  

Paso 3: Validar nuestra firma

Como medida de seguridad, firmamos las solicitudes que te enviamos usando hmac-sha256 para que puedas tener certeza de que son nuestras. Durante el proceso de onboarding, te vamos a compartir un api-key y api-secret tal como se explica en Intercambio de llaves.

En cada solicitud enviamos headers HTTP que te permitirán validar que la firma sea correcta:

• x-api-key: te permitirá identificar qué api-secret usar (en el caso que se hayan configurado múltiples pares de api-key y api-secret).

• x-signature: contiene la firma digital (body + timestamp + endpoint) que tendrás que validar para asegurar la integridad de la solicitud. La generamos usando el api-secret que te compartimos previamente. Si la firma no coincide, deberás rechazar la solicitud.

• x-timestamp : contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas regenerar la firma y verificar que es válida. En el caso de Autorizar transacción, además te permitirá validar que la firma no expiró (expiran luego de 1 minuto).

• x-endpoint : es el endpoint al que se realiza la solicitud y que utilizamos para generar la firma. Debes usar este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.

A continuación te mostramos un ejemplo de cómo verificar la validez de la firma:

Ver otros ejemplos

Paso 4: Firma de respuesta (solo para autorizar transacciones)

Para autorizar transacciones, también te pediremos que firmes la respuesta.

Los headers HTTP que deberás enviar son:

• x-api-key: este header te permitirá identificar qué api-secret tenés que usar en el caso que se hayan configurado múltiples pares de api-key y api-secret.

• x-signature: este header contiene la firma digital (body + timestamp + endpoint) que deberás verificar para asegurar la integridad del request. Si la firma no coincide, deberás rechazar el pedido.

• x-timestamp: este header contiene el momento en el que se firmó el pedido en formato unix-epoch para que puedas corroborar que la firma no expiró.

• x-endpoint: el endpoint al que se realiza el pedido y que se uso para generar la firma. Usa este header para regenerar la firma a validar, compararlo con el endpoint de tu servicio y verificar que coinciden.

Ejemplos de implementación de validación y firma de pedidos

En nuestros repositorio encontrarás ejemplos de implementación del algoritmo de generación y validación de firma en varios lenguajes. Ver repositorio

Paso 4: Respuesta para casos que no precisen firma

Esperamos una respuesta del tipo 2XX para asegurarnos de que recibiste la notificación. Caso contrario, volveremos a intentarlo.