Estándares de webhooks


Cuerpo de la respuesta
Al terminar la ejecución de un webhook, ya sea correctamente o con un error es necesario regresar una serie de información mínima con la cual se podrá tener claro el motivo de posibles errores y tener la certeza de que el webhook fue correctamente recibido.

Esta información debe ser regresada en formato JSON y con la siguiente estructura:

{
  "status": "success",  
  "short_id": "asdass",
  "message": "OK",
  "reference": "mi-id-123"
}

Campo Requerido Descripción
status SI Puede tomar valores de success o error dependiendo de si la secuencia terminó o no satisfatoriamente.
short_id SI Este parámetro se recupera del JSON enviado en la petición del webhook el cual también contiene short_id. En caso de no contar con este dato regresar como nulo.
message SI Mensaje de descripción de la operación. En caso de no tener descripción regresar como nulo.
reference SI ID de de referencia con el cual puede identificar en su sitio la operación recibida. En caso de no tenerla regresar como nulo.
Timeout
El timeout es el tiempo que tendrá que tardar su webhook como máximo para responder a la petición realizada por ComproPago en cada una de sus URL. El tiempo definido por defecto para cada petición es de 30s, en caso de requerir un tiempo mayor, tendrá que solicitar el ajuste directamente en el correo soporte@compropago.com especificando el tiempo requerido en segundos y las URL que desea agregar como webhooks.
Status Code
El status code o código de respuesta, debe tener un valor de 200 a 202, en caso de tener un valor diferente la petición se considerará fallida, entrando así en un ciclo de reintentos (3 por default) para confirmar la petición. En caso de que en los reintentos posteriores siga respondiendo un status diferente, la petición dejará de enviarse.
Webhooks Primarios y Secundarios
Su cuenta puede contar con varias URL para la recepción de los webhooks, sin embargo para la secuencia de reintentos solo se tomarán en cuenta las URL que estén definidas como primarias, para el resto de las URL se enviarán las peticiones una sola vez sin importar si la recepción fue tomada como correcta o fallida. Por defecto cada cuenta solo tiene permitido una URL primaria. En caso de requerir más de una URL deberá solicitar el ajuste de su configuración en el correo soporte@compropago.com explicando los motivos por los cuales solicita la extención, y el numero de URL primarias requeridas.
Secuencia de reintentos y recepción de eventos
Los eventos en los cuales los webhooks son disparados son pending (creación de una orden), success (aprobación de una orden) o expired (expiración de una orden) enviando la información de la orden generada a los webhooks que tenga registrados.

Es importante recalcar que si el webhook enviado con status pending no es recibido correctamente, los demás status (success o expired) no serán enviados para esa orden hasta que la petición con status pending sea correctamente recibida.