Un Webhook es una página web especial que tu software debe proveer para recibir notificaciones de eventos, como los que ocurren durante un ciclo de cobro.

Debes configurar la URL de tu webhook en cada ambiente de AdamsPay, editando los datos de tu aplicación.

Los eventos son notificados al webhook vía el método POST de un JSON que siempre contiene la propiedad notify:

{
    "notify":{
        "id":"id-unico-de-notificacion"
        ,"type":"(tipo)"
        ,"version":1
        ,"time":"hora de generación"
        ,"merchant":"id-de-tu-comercio"
        ,"app":"id-de-tu-aplicación" 
        ,"env":"ambiente"
    }
}

El contenido que el webhook debe retornar depende del evento, pero en todos los casos el HTTP status retornado debe ser en el rango 200 para indicar que el evento fue recibido.

Esto es cierto aunque el webhook ignore el evento ya que de lo contrario, AdamsPay repetirá la notificación hasta que pasen 48hs y acumular notificaciones tiene el efecto negativo de enlentecer el proceso.

El evento siendo notificado y su formato se determina por el valor de type

—

El evento debtStatus notifica a tu sistema que el estado de una deuda ha cambiado como parte del ciclo de cobro.

El POST de notificación incluirá un propiedad adicional llamada debt cuyo contenido es idéntico a la respuesta del API para comercios a una solicitud de leer una deuda.

{
    "notify":{
        "type":"debtStatus", ...
    },
    "debt":{
        "docId":"id-de-deuda",
        "objStatus":{
            "status": "active",
            "time": "2020-05-02T13:51:16+00:00",
        },
        "payStatus":{
            "status": "pending",
            "time": "2020-05-02T13:51:16+00:00",
        }, ...
    }
}

payStatus.status es el estado de cobro, cuyo valor podrá ser uno de paid y pending

objStatus.status es el estado de la deuda, cuyo valor podrá ser uno de canceled, expired, error, inactive, active y success.

1. Este evento no representa necesariamente un cobro y podría ser causada por otras razones: Tu webhook deberá comparar su estado interno contra el nuevo estado de la deuda para determinar si ocurrió un cobro o si la notificación es por otras razones (Por ejemplo: Cambió la descripción, se anuló un pago, hubo un intento de pago fallido, etc).
2. La deuda está cobrada cuando payStatus.status es paid, pero podría volver a pending si la transacción es revertida.

El contenido de la respuesta es ignorado, pero el HTTP status debe ser siempre 200 a menos que se desee que AdamsPay repita la notificación.

—

Si el webhook recibe un evento que no reconoce, es importante que el HTTP status retornado caiga en el rango 200 para que AdamsPay no reintente la notificación ya que acumularlas tiene el efecto negativo de enlentecer el proceso.

Es recomendado que el webhook valide que la notificación fue originada por AdamsPay.

Para ello, AdamsPay envía las siguientes cabeceras HTTP:

• x-adams-notify-app contienen el ID de la aplicación para la cual llega la notificación.
• x-adams-notify-hash contienen el HMAC para la validación.

El webook deberá calcular el md5 de la concatenación de:

1. La palabra adams
2. El cuerpo del POST
3. El secreto de la aplicación receptora (Se obtiene desde el UI de administración)

El valor debe ser igual al de la cabecera x-adams-notify-hash de la solicitud siendo procesada por el webhook.

$post = file_get_contents('php://input'); // el POST
$secret = 'secreto-de-tu-app'; // Obtener del UI de administración
 
$hmac_esperado = md5( 'adams' . $post . $secret );
$hmac_recibido = @$_SERVER['HTTP_X_ADAMS_NOTIFY_HASH'];
 
if( $hmac_esperado !== $hmac_recibido ){
  die('Validación ha fallado'); // Ignorar esta notificación
}
// Todo OK: Procesar