Usando Webhooks con Laravel
Los Webhooks son una manera simple de comunicar diferentes servicios. Pero aún así, para algunos desarrolladores es un tema desconocido. En este artículo, te explicaré cómo funcionan los Webhooks de manera general y también con casos de uso comunes en tu integración de Culqi.
Webhooks ¿Qué son?
En general, un webhook es un endpoint donde puedes ejecutar una acción o serie de acciones cuando es golpeado (una petición llega). Por ejemplo, si tienes integrado a Culqi en tu sitio web y se ejecuta una acción como Crear Cargo, esto haría que se realice una petición al endpoint del Webhook. Con ello, podemos reaccionar a ese evento realizando algún cambio en nuestro sistema o simplemente notificando al cliente.
La mayoría de grandes compañías ofrecen la posibilidad de integraciones de Webhooks. Servicios como Slack, Github o Facebook.
Los Webhooks son una excelente alternativa (o complemento) a las APIs que han crecido en popularidad los últimos 5 años.
Por lo que, si eres un desarrollador web, necesitarás comprender cómo funcionan los webhooks para usarlo en tus aplicaciones web. Ahora, verás la integración de Culqi y cómo manejar los Webhooks con Laravel (PHP).
Configurando Webhooks en Culqi
Si tienes un comercio creado en Culqi, puedes configurar los webhooks desde tu Panel Culqi. Entrando a Eventos > Webhooks.
Luego, añades los webhooks que necesitarás con el botón “Añadir”. Para este caso, los webhooks siguientes:
- token.creation.succeeded
- charge.creation.succeeded
Los registramos a cada uno y veremos que ya están añadidos en el listado de webhooks en Culqi.
Manejando los webhooks en Laravel
Ahora, en tu aplicación Laravel, debes colocar la ruta del webhook. En el ejemplo se ha usado la URI /webhook, así que seguiremos con eso.
Route::post(‘webhook’, ‘WebhookController@handle’);Debido a que Culqi envía una petición POST, se debe colocar como ruta POST. Para otros servicios puede ser diferente tipo de petición (GET u otros).
Como segundo paso, debes desactivar la validación CSRF token para la ruta que acabamos de configurar. Debido a que la petición viene fuera de la sesión y no contiene el CSRF token. Añadimos la ruta a las excepciones donde la validación no es necesaria. Abre el archivo VerifyCsrfToken.php de app/Http/Middleware y añades la ruta a la propiedad $except.
protected $except = [
‘webhook’,
];Después de haber todos realizado estos cambios, ahora creamos un controlador llamado WebhookController, y agregar el método handle.
class WebhookController extends Controller
{
public function handle(Request $request)
{
// Aqui ejecuta tu accion
}
}En el método handle puedes colocar la acción o acciones que desees. Puede ser cualquier cosa. Para el ejemplo, queremos registrar el evento recibido en el log de Laravel y así probar que todo está en orden.
namespace App\Http\Controllers;use Log;use Illuminate\Http\Request;use App\Http\Requests;class WebhookController extends Controller{ public function handle(Request $request) {
Log::info($request); }}
Probando Webhooks
Es hora de probar nuestra integración, crearás un token y posteriormente un cargo. Con esto, los webhooks enviarán peticiones a la URL (endpoint) que indicaste al inicio del tutorial en el Panel Culqi.
Usaré Postman para generar las pruebas de creación de token y cargo. Tu puedes probar usando tu propia integración y realizando una compra exitosa.
Recuerda que la URL que se configuró al momento de crear los webhooks debe ser accesible y pública. Por lo que si te encuentras en tu entorno local (localhost) puedes usar ngrok para generar una URL pública durante el desarrollo.
Primero, creamos el token y luego el cargo exitosamente.
Ahora, revisamos el log de nuestra aplicación en Laravel. Si todo está correcto deberías poder observar los JSON de las peticiones que envió Culqi hacia el Webhook con cada evento.
Y también en el Panel Culqi, dentro de Eventos > Historial de eventos.
Una vez que sabemos que la comunicación entre el webhook y el servicio es correcta. Mejoramos un poco el código del controlador para poder identificar el tipo de evento que está llegando y tomar acciones diferenciadas.
class WebhookController extends Controller
{
public function handle(Request $request)
{
if($request->input('object') == 'event') {
switch ($request->type) {
case 'token.creation.succeeded':
//codigo para el evento aqui
Log::info('Evento recibido de TOKEN creado');
break;
case 'charge.creation.succeeded':
//codigo para el evento aqui
Log::info('Evento recibido de CARGO creado');
break;
}
Log::info($request);
}
}
}Con esto integrado puedes a partir de ahora tener la posibilidad de enviar notificaciones, correos de aviso, SMS a tus usuarios (o de manera interna) ante estos eventos. Según tus necesidades, son muchas las posibilidades de aplicaciones.
Casos de uso reales de Webhooks
Culqi
En Culqi puedes usar los webhooks que ofrecemos para casos principales como el de las suscripciones. Y notificar al cliente cuando su cargo a su tarjeta fue fallido. Con esto, ante la cantidad de reintentos que consideres correcta puedes desuscribirlo de tu sitio asi como en Culqi.
Mailchimp
Este servicio de correo transaccional y marketing ofrece la posibilidad de poder recibir los eventos que envuelven los correos enviados. Tales como: Apertura de los correos, click en los enlaces, rebote de correos, etc
Twilio
Twilio es por excelencia el servicio el cual usar cuando necesitas enviar SMSs. Lo puedes usar oportunamente para mantener una comunicación rápida con tus clientes, además, de usar los emails. También ofrecen Webhooks.
Conclusiones
- Los beneficios de los Webhooks en pocas palabras: notificaciones instantáneas en tiempo real.
- Mayor eficiencia y permite automatización de acciones.
- Al contrario del uso de la API para ejecutar consultas recurrentes, es mejor utilizar los webhooks para recibir cambios a través de eventos con el fin de mantener la sincronización entre los sistemas.
- API + Webhooks = ¡Infinitas posibilidades!
