Los eventos te permiten recibir notificaciones de GoCardless en tiempo real cuando sucede algo en tu cuenta, para que puedas tomar medidas automatizadas en respuesta, por ejemplo:
- Cuando se rechaza un pago por falta de fondos, reintentarlo automáticamente
- Cuando un cliente cancela su mandato con el banco, suspender la cuenta
- Cuando la suscripción de un cliente genera un nuevo pago, registrar ese pago en su cuenta
Hay dos formas de recibir información de un evento:
Webhooks: un webhook es una solicitud que GoCardless envía a tu servidor para alertarte de un evento.
El extremo de eventos: puedes hacer una lista de eventos directamente desde el extremo de eventos si deseas extraer la información tú mismo. Puede ser la mejor opción si vas a procesar un gran volumen de eventos.
Procesamiento de eventos mediante webhooks
Hacer que localhost esté accesible desde internet con ngrok
Para empezar a utilizar webhooks, tu código debe estar accesible desde internet para que GoCardless pueda localizarlo con solicitudes HTTP. Si trabajas de forma local, la forma más sencilla de hacerlo es con ngrok.
Descárgalo y sigue las instrucciones de la página para instalarlo (deberás descomprimir el archivo y, a continuación, poner el ngrok binario disponible en la Ruta de acceso).
A continuación, simplemente ejecuta ngrok http <puerto>
, donde <puerto> es el puerto donde se esté ejecutando tu servidor web (por ejemplo, ngrok http 8000
, si se está ejecutando en el puerto 8000).
Verás dos enlaces que reenvían a localhost:8000. Selecciona la URL que comienza con https y cópiala en el portapapeles.
En la cuenta de pruebas, puedes utilizar una URL HTTP para los webhooks, pero para utilizarlos en un entorno real, el extremo debe tener seguridad HTTPS.
Agregar una URL de webhook en el panel de control de GoCardless
Para comenzar a recibir webhooks, deberás agregar un extremo de webhook desde el panel de control aquí.
Introduce la URL HTTPS de antes y agrega la ruta de acceso en la que estará disponible el controlador de webhook, asígnale un nombre al extremo y, luego, haz clic en "Crear extremo de webhook". A continuación, haz clic en el extremo nuevo de la lista y copia el secreto en el portapapeles.
Creación de un controlador de webhook
Los webhooks son solicitudes HTTP POST hechas a la URL que has proporcionado, con un cuerpo JSON.
Lo primero que debes hacer cuando recibes un webhook es comprobar su firma; esto garantiza que sea realmente de GoCardless y no haya sido falsificado. Se proporciona una firma en el encabezado Firma de webhook de la solicitud. Solo debemos calcular la firma nosotros mismos mediante el JSON publicado en POST y el secreto del extremo de webhook (que hemos copiado anteriormente), y compararla con la del encabezado.
Si coinciden, el webhook es genuino, porque solo tú y GoCardless conocéis el secreto. Es importante que protejas el secreto y lo cambies periódicamente mediante el panel de control.
Una vez que se haya autenticado la firma, puedes enviar una respuesta 2xx antes de procesar la carga JSON.
Ten en cuenta que si no das una respuesta 2xx en un plazo de 10 segundos, el webhook se rechazará y, posteriormente, reintentaremos el webhook en los intervalos mencionados aquí. Por lo tanto, es importante procesar los webhooks de forma asincrónica para evitar que se agote el tiempo si recibes varios eventos a la vez. Es decir, envía una respuesta 2xx antes de procesar el webhook.
Una vez que hayas realizado las acciones que deseas realizar para un evento, te recomendamos que también crees un registro para evitar procesar accidentalmente lo mismo dos veces.
Para obtener ejemplos detallados de código sobre cómo comprobar la firma, consulta el enlace aquí.
Prueba del controlador de webhook
Con la funcionalidad "Enviar webhook de prueba" del panel de control, resulta sencillo empezar a utilizar webhooks.
Selecciona el extremo de webhook que creaste anteriormente, configura el tipo de recurso de mandatos y la acción a cancelada. Puedes configurar los datos de la causa y del evento como desees. Luego, haz clic en "Enviar webhook de prueba".
A continuación, actualiza la página. Generalmente, el webhook aparece de inmediato, pero en ocasiones es posible que tengas que actualizar unas cuantas veces. Realizaremos una solicitud a tu extremo y el webhook aparecerá en la lista; haz clic en él. Si todo funciona correctamente, verás un código de respuesta de 200 Aceptar.
Reintentos y fallos de webhooks
Es posible que al enviar webhooks se produzca algún fallo debido a distintos motivos, tales como:
- Tiempo caducado: no recibimos ninguna respuesta 2xx dentro de los 10 segundos posteriores al envío del webhook.
- Acceso no autorizado: se requiere autorización del servidor, pero la autenticación proporcionada no es válida.
- La solicitud se ha redirigido: no seguimos ninguna redirección HTTP, por lo que las tratamos como fallos de webhook.
Si un webhook falla, reintentaremos el webhook hasta 8 veces en intervalos ascendentes, es decir, de 1 minuto, 2 minutos, 10 minutos, etc.
Procesamiento de los eventos dentro de los webhooks
Un webhook puede contener varios eventos, y cada uno tiene un resource_type (que nos indica para qué tipo de recurso es el evento, por ejemplo "pagos" o "mandatos"), una acción (que nos indica qué ha ocurrido con el recurso, por ejemplo, la acción cancelado para un mandato) y datos (que indican por qué ha ocurrido el evento).
Puedes ver una lista completa de las combinaciones posibles en la documentación de referencia y un ejemplo de un controlador de eventos aquí.
Puedes agregar compatibilidad para tantos source_types
y acciones diferentes como desees, así como utilizar todos los demás datos que te proporcionamos con los eventos.
Activación de webhooks
Cuando desarrolles la integración, desearás recibir webhooks realistas para poder comprobar cómo responde la integración.
Puedes activar webhooks mediante nuestro simulador de escenarios o con la herramienta "Enviar webhook de prueba"; solo tienes que hace clic en "Enviar webhook de prueba" en la página "Desarrolladores" del panel de control.
Antes de utilizar la herramienta "Enviar webhook de prueba", deberás tener un extremo de webhook configurado. Haz clic en "Crear" y en "Extremos de webhook" en la página "Desarrolladores" del panel de control. Si has creado alguna aplicación, su extremo de webhook también estará disponible.
A continuación, podrás personalizar el webhook. En primer lugar, elige los extremos de webhook, y luego ajusta el tipo de recurso, la acción, la causa, los datos del evento y el identificador asociado.
En el código, es probable que utilices el identificador para localizar registros en la base de datos y tomar las medidas pertinentes en función del webhook.
Si haces clic en "Enviar webhook de prueba", enviaremos el webhook al extremo que elijas, generalmente en unos pocos segundos.
Al actualizar la página, el webhook que acabas de enviar aparecerá en la lista de webhooks.
Si haces clic en un webhook, podrás ver la solicitud completa, además de la respuesta. Esto es realmente útil para fines de depuración.
Puedes volver a enviar un webhook que ya has enviado. Para ello, selecciónalo de la lista y haz clic en "Reintentar" en la esquina superior derecha.
Procesamiento de los eventos mediante el extremo de eventos
Una alternativa a los webhooks es extraer la información directamente desde el extremo de eventos.
Se trata de una alternativa popular que proporciona más control sobre cuándo procesas los eventos y elimina las complejidades que rodean los fallos y reintentos de webhooks.
Esto implicaría hacer una llamada para generar una lista de eventos en determinados momentos del día, mediante el uso del parámetro created_at[gt] para enumerar los eventos creados desde el último sondeo.
También puedes optar por extraer o gestionar eventos específicos mediante cualquiera de los parámetros enumerados aquí. Por ejemplo, para recibir únicamente los eventos de mandatos cancelados, enviarías una solicitud similar a la siguiente:
GET https://api-sandbox.gocardless.com/events?action=cancelled&resource_type=mandate HTTP/1.1
También cabe destacar que la mayoría de los eventos se crea cuando recibimos (de 8 a 11 h BST) y enviamos (de 15 a 18 h BST) informes al banco. Por lo tanto, generalmente recomendamos consultar el extremo alrededor del mediodía, por la tarde y en cualquier otro momento que desees.