Cómo conectar Bubble con Easytools: guía paso a paso
Mira el tutorial sobre cómo conectar Bubble con Easytools, preparado por Chris Rapacz, fundador de Sendby.io. En este tutorial, Chris muestra cómo integró su app de Bubble con Easytools para cobrar pagos y gestionar de forma eficaz las suscripciones y el acceso de los usuarios.
Y aquí tienes también una transcripción con todos los enlaces y detalles que Chris menciona en su vídeo.
1. Configura tu base de datos de Bubble
En tu tipo de dato User (usuario), necesitarás algunos campos personalizados para hacer seguimiento de las suscripciones:
- easytools_customer_id - se asigna después de una transacción con éxito
- renewal_date (fecha de renovación)
- subscribed (suscrito) - crítico; controla el acceso
- subscription_date (fecha de suscripción)
- subscription_one_time (suscripción de pago único)
- subscription_type (tipo de suscripción) - por ejemplo, “monthly” (mensual), “lifetime” (de por vida)
- trial_ends_at (fin del periodo de prueba)
Nota: el campo más importante es subscribed. Si es yes (sí), el usuario puede generar contenido. Si es no, deberás redirigirlo a Easytools para que se suscriba.
2. Entiende los webhooks de Easytools
Easytools ofrece distintos tipos de webhooks, entre ellos:
- subscription_created (suscripción creada) o single_product_bought (producto único comprado)
- product_assigned (producto asignado)
Cada webhook llega con una estructura JSON distinta. Todos los eventos se envían a una misma URL, así que tendrás que gestionar el enrutamiento dentro de tu workflow de backend en Bubble.
Puedes consultar la lista completa de eventos de webhook de Easytools aquí.
3. Configura la URL del webhook
En Easytools, ve a API & Webhook settings (configuración de API y webhooks) y configura tu Webhook URL:
https://your-app.bubbleapps.io/version-test/api/1.1/wf/easy_payments?api_token=YOUR_API_KEY
- easy_payments → nombre de tu workflow de backend en Bubble
- api_token → se genera en Bubble, en Settings > API > Generate private key
Asegúrate de usar la versión correcta en la URL:
- Desarrollo: incluye version-test
- Producción: no incluye version-test
4. Añade verificación del webhook (opcional, pero muy recomendable)
Para proteger tu webhook:
- Genera una Webhook Signing Key (clave de firma del webhook) en Easytools.
- Usa el plugin Toolbox en Bubble.
- En tu workflow de backend (easy_payments), añade un paso Server Script.
- Pega tu clave de firma y compara el hash calculado con la cabecera x-webhook-signature de Easytools.
Si coinciden, continúa con el workflow. Si no, termínalo de inmediato.
Nota: no podrás volver a ver la clave de firma después de generarla, así que guárdala en un lugar seguro.
5. Enruta los eventos del webhook a sub-workflows
Usa tu webhook principal (easy_payments) como enrutador. Según el tipo de evento, redirige a workflows de backend específicos:
Ejemplos:
- process_product_assigned
- process_subscription_expired
Solo el webhook principal debe ser público. Estos sub-workflows deben permanecer privados.
6. Configura los sub-workflows
Para process_product_assigned:
- Activa “Ignore privacy rules” (ignorar reglas de privacidad).
- Define manualmente los parámetros que vas a recibir del webhook:
- subscription_type
- subscription_one_time
- is_subscription
- price
- custom_id
- etc.
Pasos:
- (Opcional) Envíate un email a ti mismo para hacer pruebas.
- Modifica al usuario correspondiente en tu base de datos:
- Pon subscribed = yes si hay una suscripción activa y válida.
- Actualiza otros campos como subscription_type, renewal_date, trial_ends_at, etc.
- Usa lógica condicional:
- Si subscription_one_time = yes → subscribed = yes
- Si tanto subscription_one_time como is_subscription son no → subscribed = no
Para process_subscription_expired:
- Modifica al usuario:
- Pon subscribed = no
- Pon access_expired = yes
- Opcionalmente, envíate un email de notificación.
7. Gestiona varios formatos de JSON
Bubble espera una estructura JSON coherente, pero Easytools envía estructuras distintas según el evento.
Para solucionarlo:
- Copia todos los ejemplos de JSON de la documentación de Easytools.
- Combínalos en un único JSON.
- Ve a tu workflow easy_payments en Bubble y haz clic en “Detect data” (detectar datos).
- Usa Postman para enviar tu JSON combinado:
- Método: POST
- Pega la URL del webhook
- Body: raw JSON
- Bubble reconocerá la estructura. Revisa el tipo de cada campo (por ejemplo, número, texto, fecha).
Archivo JSON combinado disponible
Aquí tienes un esquema JSON combinado, generado por Chris, que incluye todas las claves relevantes de todos los eventos de webhook de Easytools. Puedes usar este archivo durante la detección en Bubble para inicializar correctamente el endpoint del webhook.
Descarga el archivo JSON combinado.
Asegúrate de usar este archivo cuando envíes con Postman la solicitud de prueba a Bubble durante el paso “Detect data”. Esto garantiza que Bubble capture todos los campos posibles usados en los distintos eventos de webhook de Easytools.
Para usar el archivo:
- Abre el archivo adjunto easytools_merged_webhook.json.
- Copia su contenido en el body en bruto de tu solicitud en Postman.
- Envía la solicitud POST a tu URL de detección de webhook en Bubble.
Después de enviarlo:
- Bubble mostrará todos los campos detectados.
- Revisa cada uno y confirma que los tipos de datos son correctos:
- Las fechas deben ser de tipo date.
- Los números deben ser number.
- Los campos de texto deben ser text.
Cuando todo esté correcto, haz clic en Save (guardar) en Bubble para finalizar la configuración del webhook.
8. Haz coincidir a los usuarios por email
Para asignar el webhook al usuario correcto:
- Haz que los usuarios creen primero una cuenta en tu app.
- Prellena el formulario de checkout de Easytools con Current User’s email (email del usuario actual).
- En tu workflow del webhook, busca al usuario con:
Search for Users where email = request.body.customer_email
Si el email no coincide, Bubble no podrá asignar la compra a ningún usuario. Fuerza la coherencia del email desde el principio.
9. Prueba el flujo completo
- Pon el campo subscribed de un usuario de prueba en no en la base de datos de Bubble.
- Intenta acceder a una función protegida → el usuario es redirigido al checkout de Easytools.
- Realiza un pago de prueba.
- De vuelta en Bubble:
- El webhook se recibe y se verifica.
- El campo subscribed del usuario se actualiza.
- La app lo detecta y desbloquea el acceso.
Nota: normalmente el webhook tarda entre 8 y 10 segundos en procesarse.
Puedes:
- Añadir un retraso de 20 segundos en la redirección de Easytools.
- Mostrar una pantalla de “procesando” mientras compruebas periódicamente si subscribed = yes.
Notas finales
- Los workflows de backend en Bubble solo están disponibles en planes de pago.
- Prueba siempre tanto los pagos únicos como las suscripciones recurrentes.
- Asegúrate de que la lógica de tu webhook sea segura, sobre todo al gestionar pagos.