Notificaciones

AutoPay envía notificaciones cuando ocurran eventos sobre los autopagos pertenecientes a tu comercio.

Para poder recibir notificaciones el comercio debe exponer un endpoint tipo POST con el contrato mencionado en esta documentación, además debe existir en la plataforma el comercio registrado.

Tipos de eventos

Actualmente, AutoPay envía notificaciones para los siguientes eventos:

Evento
Descripción
AUTOPAY_CREATED
Indica que un autopay ha sido creado, puede suceder luego de que el usuario finalize la sesión de creación de autopago y autorice la creación del mismo
AUTOPAY_UPDATED
Indica que un autopay ha sido actualizado, puede suceder cuando el usuario haya cambiado en medio de pago, el comercio haya cambiado la frecuencia de pago, etc.
AUTOPAY_TRANSACTION_FAILED
Indica que un intento de pago automático ha fallado.
AUTOPAY_CANCELED
Indica que un autopay ha sido cancelado.

Validación del webhook

Debido a que la notificación llega desde un sistema externo a tus servidores, es importante validar que el mensaje es autentico y viene de un origen confiable. Para esto se hace uso de una firma incluida en el mensaje y que fue generada usando el secretKey proveniente del sitio que solo conocen los sistemas involucrados. Para conocer más de tu secretKey, consulta la documentación de Autenticación

Para iniciar tu validación debes tener disponible el secretKey asociado con tu comercio.

Identificar el algoritmo para identificar el algoritmo usado en la firma, ten en cuenta lo siguiente:

  • Si el campo signature comienza con el prefijo sha256:, entonces la firma fue generada usando SHA-256.

Extraer la firma plana: Una vez identificado el algoritmo, identifica el campo signature.

  • Si el prefijo sha256: está presente, debes eliminarlo y con esto obtendrás la firma plana que debes comparar, llamaremos a esta receivedSignature.

Generar tu propia firma Una vez identificado el algoritmo, debes generar tu propia firma usando la siguiente fórmula:

  • Para SHA-256: SHA-256(id + type + date + secretKey)

Con esto obtendrás la firma generada por tu sistema, llamaremos a esta generatedSignature. Ten encuenta que los datos para generar la firma se encuentra en el detalle del webhook, ver más en Contrato de webhook.

Comparar firmas: Finalmente, compara la firma que generaste (generatedSignature) con la firma que recibiste en el mensaje (receivedSignature). Si ambas firmas son iguales, entonces la notificación es auténtica y puedes proceder a actualizar el estado de la sesión en tu sistema.

Al recibir una notificación, se recomienda llamar a la API de consulta de AutoPagos para obtener más detalles sobre el cambio, de manera que siempre se tenga información precisa y actualizada.

POST{{baseURl}}/autopay/webhook

Notificaciones

baseURL: Es la URL base del aplicativo del cliente/comercio la cual debe ser entregada por el mismo y configurada en el momento del onboarding del comercio con AutoPay.

Debe exponer un endpoint conforme al siguiente contrato. AutoPay enviará notificaciones a dicho endpoint cada vez que un autopago sea creado, se haya actualizado el medio de pago, sea cancelado o fallado algún pago.

Solicitud

  • Name
    id
    Type
    string
    is Required
    REQUIRED
    Description

    Identificador único del AutoPago

    Ejemplo:2972c13d-6315-4da3-80d7-64c24eb232ad
    Formato:uuid
    Longitud máxima:36
    Longitud mínima:36
  • Name
    type
    Type
    string
    is Required
    REQUIRED
    Description

    Tipo de evento notificado. Ver más en Eventos Webhook.

    Valores permitidos:AUTOPAY_CREATEDAUTOPAY_UPDATEDAUTOPAY_CANCELEDAUTOPAY_TRANSACTION_FAILED
  • Name
    date
    Type
    string
    is Required
    REQUIRED
    Description

    Fecha y hora en la que se lanzó por primera vez el evento. En formato ISO 8601.

    Ejemplo:2025-09-29T17:09:29-05:00
    Formato:date-time
  • Name
    signature
    Type
    string
    is Required
    REQUIRED
    Description

    Firma digital del contenido del webhook para validación. Ver más en Validación de Webhooks.

    Ejemplo:sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s
  • Name
    reference
    Type
    string
    is Required
    REQUIRED
    Description

    Referencia del AutoPago proporcionada por el cliente/comercio, esta referencia debe ser unica activa por comercio.

    Ejemplo:ACC00012345
    Longitud máxima:32
  • Name
    additional
    Type
    object
    is optional
    CONDITIONAL
    Description

    Objeto que contiene información relevante para identificar el autopago e información del evento.

Solicitud

POST
{{baseURl}}/autopay/webhook
{
    "id": "2972c13d-6315-4da3-80d7-64c24eb232ad",
    "reference": "ACC00012345",
    "type": "AUTOPAY_CREATED",
    "date": "2023-01-19 15:57:23",
    "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

Respuesta

El webhook fue recibido correctamente.

  • Name
    status
    Type
    Status
    is optional
    Description

    Estructura para definir estados de respuestas


Respuesta

    {
      "status": {
         "status": "OK",
         "reason": "00",
         "message": "Respuesta exitosa",
         "date": "2025-09-29T17:09:29-05:00"
      },
    }