Cómo probar Webhooks cuando está desarrollando localmente

Los webhooks pueden ser utilizados por un sistema externo para notificar a su sistema sobre un determinado evento o actualización. Probablemente el tipo más conocido es aquel en el que un proveedor de servicios de pago (PSP) informa a su sistema sobre las actualizaciones de estado de los pagos.

A menudo vienen en la forma en que escuchas en una URL predefinida. Por ejemplo, //example.com/webhooks/payment-update. Mientras tanto, el otro sistema envía una solicitud POST con una cierta carga útil a esa URL (por ejemplo, una identificación de pago). Tan pronto como llega la solicitud, obtiene el ID de pago, le pide al PSP el estado más reciente a través de su API y luego actualiza su base de datos.

Se pueden encontrar otros ejemplos en esta excelente explicación sobre Webhooks. //sendgrid.com/blog/whats-webhook/.

La prueba de estos webhooks se realiza sin problemas siempre que el sistema sea de acceso público a través de Internet. Este podría ser su entorno de producción o un entorno de ensayo de acceso público. Se vuelve más difícil cuando está desarrollando localmente en su computadora portátil o dentro de una máquina virtual (VM, por ejemplo, una caja Vagrant). En esos casos, la parte que envía el webhook no puede acceder públicamente a las URL locales. Además, monitorear las solicitudes que se envían es difícil, lo que puede dificultar el desarrollo y la depuración.

¿Qué resolverá este ejemplo?

  • Prueba de webhooks desde un entorno de desarrollo local, al que no se puede acceder a través de Internet. El servicio que envía los datos al webhook desde sus servidores no puede acceder a él.
  • Supervise las solicitudes y los datos que se envían, pero también la respuesta que genera su aplicación. Esto permitirá una depuración más sencilla y, por lo tanto, un ciclo de desarrollo más corto.

Prerrequisitos:

  • Opcional : en caso de que esté desarrollando usando una máquina virtual (VM), asegúrese de que esté funcionando y asegúrese de que los siguientes pasos se realicen en la VM.
  • Para este tutorial, asumimos que tiene un vhost definido en webhook.example.vagrant. Usé una máquina virtual Vagrant para este tutorial, pero puedes elegir el nombre de tu vhost.
  • Instale ngroksiguiendo las instrucciones de instalación. Dentro de una VM, encuentro que la versión de Node también es útil: //www.npmjs.com/package/ngrok, pero siéntase libre de usar otros métodos.

Supongo que no tiene SSL ejecutándose en su entorno, pero si lo tiene, no dude en reemplazar el puerto 80 con el puerto 433 y //con //los ejemplos a continuación.

Hacer que el webhook sea comprobable

Supongamos el siguiente código de ejemplo. Usaré PHP, pero lo leeré como pseudocódigo ya que dejé algunas partes cruciales (por ejemplo, claves de API, validación de entrada, etc.)

El primer archivo: payment.php . Este archivo crea un objeto de pago y luego lo registra con el PSP. Luego, obtiene la URL que el cliente necesita visitar para pagar y redirige al usuario al cliente allí.

Tenga webhook.example.vagranten cuenta que en este ejemplo es el vhost local que hemos definido para nuestra configuración de desarrollo. No es accesible desde el mundo exterior.

 123, 'amount' => 25.00, 'description' => 'Test payment', 'redirect_url' => '//webhook.example.vagrant/redirect.php', 'webhook_url' => '//webhook.example.vagrant/webhook.php', ]; $payment = $paymentProvider->createPayment($payment); header("Location: " . $payment->getPaymentUrl());

Segundo archivo: webhook.php . Este archivo espera a ser llamado por el PSP para recibir notificaciones sobre actualizaciones.

getPayment($paymentId); $status = $paymentInfo->getStatus(); // Perform actions in here to update your system if ($status === 'paid') { .. } elseif ($status === 'cancelled') { .. }

No se puede acceder a la URL de nuestro webhook a través de Internet (recuerde:) webhook.example.vagrant. Por lo tanto, la PSP nunca llamará al archivo webhook.php . Su sistema nunca conocerá el estado del pago. En última instancia, esto conduce a que los pedidos nunca se envíen a los clientes.

Afortunadamente, ngrok puede resolver este problema. ngrok se describe a sí mismo como:

ngrok expone servidores locales detrás de NAT y cortafuegos a la Internet pública a través de túneles seguros.

Comencemos un túnel básico para nuestro proyecto. En su entorno (ya sea en su sistema o en la VM) ejecute el siguiente comando:

ngrok http -host-header=rewrite webhook.example.vagrant:80

Lea sobre más opciones de configuración en su documentación: //ngrok.com/docs.

Aparecerá una pantalla como esta:

¿Qué acabamos de empezar? Básicamente, ordenamos ngrokiniciar un túnel //webhook.example.vagranten el puerto 80. Ahora se puede acceder a esta misma URL a través de //39741ffc.ngrok.ioo //39741ffc.ngrok.io. Cualquiera que conozca esta URL puede acceder a ellos públicamente a través de Internet.

Tenga en cuenta que obtiene HTTP y HTTPS disponibles de inmediato. La documentación ofrece ejemplos de cómo restringir esto solo a HTTPS: //ngrok.com/docs#bind-tls.

Entonces, ¿cómo hacemos que nuestro webhook funcione ahora? Actualice payment.php al siguiente código:

 123, 'amount' => 25.00, 'description' => 'Test payment', 'redirect_url' => '//webhook.example.vagrant/redirect.php', 'webhook_url' => '//39741ffc.ngrok.io/webhook.php', ]; $payment = $paymentProvider->createPayment($payment); header("Location: " . $payment->getPaymentUrl());

Ahora, le dijimos a la PSP que llamara a la URL del túnel a través de HTTPS. ngrok se asegurará de que se llame a su URL interna con una carga útil no modificada, tan pronto como el PSP llame al webhook a través del túnel.

¿Cómo monitorear las llamadas al webhook?

La captura de pantalla que ha visto anteriormente ofrece una descripción general de las llamadas que se realizan al host del túnel. Estos datos son bastante limitados. Afortunadamente, ngrokofrece un panel de control muy agradable, que le permite inspeccionar todas las llamadas:

No voy a profundizar mucho en esto porque se explica por sí mismo tan pronto como lo tiene funcionando. Por lo tanto, explicaré cómo acceder a él en la caja de Vagrant, ya que no funciona de inmediato.

El panel le permitirá ver todas las llamadas, sus códigos de estado, los encabezados y los datos que se envían. También verá la respuesta que generó su aplicación.

Otra característica interesante del tablero es que le permite reproducir una determinada llamada. Supongamos que su código de webhook tuvo un error fatal, sería tedioso iniciar un nuevo pago y esperar a que se llame al webhook. Reproducir la llamada anterior acelera el proceso de desarrollo.

Se puede acceder al panel de forma predeterminada en // localhost: 4040.

Tablero en una VM

Para que esto funcione dentro de una máquina virtual, debe realizar algunos pasos adicionales:

Primero, asegúrese de que se pueda acceder a la VM en el puerto 4040. Luego, cree un archivo dentro de la VM con esta configuración:

web_addr: 0.0.0.0:4040

Ahora, elimine el ngrokproceso que aún se está ejecutando e inícielo con este comando ligeramente ajustado:

ngrok http -config=/path/to/config/ngrok.conf -host-header=rewrite webhook.example.vagrant:80

You will get a screen looking similar to the previous screenshot though the ID’s have changed. The previous URL doesn’t work anymore, but you got a new URL. Also, the Web Interface URL got changed:

Now direct your browser to //webhook.example.vagrant:4040 to access the dashboard. Also, make a call to //e65642b5.ngrok.io/webhook.php.This will probably result in an error in your browser, but the dashboard should show the request being made.

Final remarks

The examples above are pseudo-code. The reason is that every external system uses webhooks in a different way. I tried to give an example based on a fictive PSP implementation, as probably many developers have to deal with payments at some moment.

Please be aware that your webhook URL can also be used by others with bad intentions. Make sure to validate any input being sent to it.

Preferably also add a token to the URL which is unique for each payment. This token must only be known by your system and the system sending the webhook.

Good luck testing and debugging your webhooks!

Note: I haven’t tested this tutorial on Docker. However, this Docker container looks like a good starting point and includes clear instructions. //github.com/wernight/docker-ngrok.

Stefan Doorn

//github.com/stefandoorn

//twitter.com/stefan_doorn

//www.linkedin.com/in/stefandoorn