¿Qué es un Webhook?
Los Webhooks te permiten recibir notificaciones de las transacciones realizadas a algún servicio web que tu configures en tu cuenta. Esto te permite saber, por ejemplo, cuando se ha realizado un cargo a una tarjeta o cuando un depósito se ha realizado con éxito.
Nota: Si deseas manejar los webhooks vía API, consulta la referencia aqui
Objeto Webhook
Cada vez que se realice una transacción, Openpay enviará un objecto JSON a las URL’s registradas para recibir webhooks. Openpay puede agregar más campos en un futuro, o agregar nuevos valores a campos existentes, por lo que es recomendado que tu Webhook pueda manejar datos adicionales desconocidos.
Parámetros
El objeto webhook contiene los siguientes datos:
Campo
Descripción
type
string
El tipo de evento que generó la notificación
event_date
timestamp
Fecha de creación del evento en formato ISO 8601
transaction
string
El objeto de Transacción relacionado con el evento. No enviado en notificaciones de tipo verification.
verification_code
string
El código de verificación del Webhook. Enviado solamente en notificaciones de tipo verification.
Todas las notificaciones de las transacciones se enviarán a las URL’s que tengas registradas. Para distinguir una transacción, utiliza la propiedad type
Nota: Openpay intentará entregar la notificación hasta recibir una respuesta de éxito. Esto puede causar que algunas notificaciones se envíen dos veces, por lo que debes estar preparado para poder recibir la misma notificación mas de una vez.
Ejemplo:
{
"type" : "charge.succeeded",
"event_date" : "2013-11-22T15:09:38-06:00",
"transaction" : {
"amount" : 2000.0,
"authorization" : "801585",
"method" : "card",
"operation_type" : "in",
"transaction_type" : "charge",
"card" : {
"type" : "debit",
"brand" : "mastercard",
"address" : {
"line1" : "Calle #1 Interior #2",
"line2" : null,
"line3" : null,
"state" : "Queretaro",
"city" : "Queretaro",
"postal_code" : "76040",
"country_code" : "MX"
},
"card_number" : "1881",
"holder_name" : "Card Holder",
"expiration_month" : "10",
"expiration_year" : "14",
"allows_charges" : true,
"allows_payouts" : true,
"creation_date" : "2013-11-22T15:09:32-06:00",
"bank_name" : "BBVA BANCOMER",
"bank_code" : "012"
},
"status" : "completed",
"id" : "tlxcm4vprtz74qoenuay",
"creation_date" : "2013-11-22T15:09:33-06:00",
"description" : "Description",
"error_message" : null,
"order_id" : "oid_14235"
}
}Características de un servicio Webhook válido
- Endpoint: Solo dominios (No IPs). ejemplo: https://notifications.merchant.com
- Puerto: 443/TCP, 1518/TCP, 1519/TCP, 8443/TCP y 10443/TCP
- Protocolo: HTTPS/TLS_1.2
- Certificado: Válido (firmado por CA pública y match con dominio).
Tipos
Tipo
Descripción
verification
La notificación contiene el código de verificación del Webhook
charge.created
Se creó un cargo para ser pagado por transferencia bancaria.
charge.succeeded
Indica que el cargo se ha completado (tarjeta, banco o tienda)
charge.refunded
Un cargo a tarjeta fue reembolsado.
payout.created
Se ha programado un pago.
payout.succeeded
Se ha enviado el pago.
payout.failed
El pago fue rechazado.
transfer.succeeded
Se ha realizado una transferencia entre dos clientes.
fee.succeeded
Se ha cobrado una comisión a un cliente.
spei.received
Se han agregado fondos a una cuenta mediante SPEI.
chargeback.created
Se ha recibido un contracargo de un cargo a tarjeta
chargeback.rejected
El contracargo se ha ganado a favor del comercio
chargeback.accepted
El contracargo se ha perdido. Se ha creado una transacción tipo contracargo que descontará los fondos de tu cuenta.
Tu servidor debe estar preparado para aceptar notificaciones de tipos no conocidos, para asegurar una compatibilidad con futuras versiones.
Registro
Para configurar un Webhook sigue los siguientes pasos:
Entra al Dashboard de Openpay utilizando tu correo y tu contraseña
Da click en tu nombre para accesar a tu perfil de comercio.
En la sección de Webhooks, selecciona la opción +Agregar Webhook.
En el formulario que aparece, indica la URL completa de tu webhook, incluyendo el protocolo a usar. Es recomendado utilizar https.
Si tu Webhook requiere autenticación HTTP, configúrala. Actualmente solo se soporta autenticación HTTP Basic.
Da click en el botón Guardar.
Verificación
Al terminar la configuración de registro, Openpay enviará mediante POST un mensaje JSON a la URL indicada, conteniendo un objeto de notificación Webhook. Tu servicio deberá guardar el código de verificación de alguna manera, y regresar el estado 200 OK.
Si por alguna razón requieres que se te envíe de nuevo el código de verificación, selecciona la opción Reenviar Código. Un nuevo código de verificación será generado y enviado a la URL proporcionada.
Una vez que ya tengas el código de verificación del Webhook, selecciona la opción de Verificar e introduce el código proporcionado en el objeto de la notificación. Esto activará el Webhook en Openpay, y empezarás a recibir notificaciones de las transacciones realizadas a partir de ese momento.
Ejemplo:
{
"type" : "verification",
"event_date" : "2013-11-22T11:04:49-06:00",
"verification_code" : "UY1qqrxw"
}Implementación
Para implementar tu Webhook, solo tienes que crear un servicio Web con una URL a la que Openpay pueda enviar peticiones POST.
Tu Webhook debe manejar los diferentes tipos de notificaciones, incluyendo recibir el código de verificación, para que puedas darlo de alta en Openpay.
Tu Webhook también deberá poder recibir tipos de notificaciones inesperados, para asegurar compatibilidad con futuras versiones.
Los Webhook deberán regresar un estado HTTP 200 OK siempre que reciban una notificación, de otra manera Openpay reintentará el envío continuamente.
Eliminación
En cualquier momento puedes seleccionar la opción -Eliminar desde el dashboard para eliminar un Webhook y dejar de recibir notificaciones a esa URL.
