How to connect Bubble with Easytools – a step-by-step guide

Watch the tutorial on connecting Bubble with Easytools prepared by Chris Rapacz, founder of Sendby.io. In this tutorial, Chris demonstrates how he integrated his Bubble app with Easytools to collect payments and effectively manage subscriptions and user access.

And here's also a transcript with all the links and details Chris mentions in his video

1. Set up your Bubble database

In your User data type, you’ll need a few custom fields to track subscriptions:

• easytools_customer_id – assigned after a successful transaction
• renewal_date
• subscribed – critical; controls access
• subscription_date
• subscription_one_time
• subscription_type – e.g., “monthly”, “lifetime”
• trial_ends_at

Note: The most important field is subscribed. If it's yes, the user can generate content. If it's no, you will redirect them to Easytools to subscribe.

2. Understand Easytools webhooks

Easytools different types of webhooks, including:

• subscription_created or single_product_bought
• product_assigned

Each webhook comes with a different JSON structure. All events are sent to one URL, so you’ll need to handle routing within your Bubble backend workflow.

The full list of Easytools webhook events can be found here.

3. Set up the webhook URL

In Easytools, go to API & Webhook settings and configure your Webhook URL:

https://your-app.bubbleapps.io/version-test/api/1.1/wf/easy_payments?api_token=YOUR_API_KEY

• easy_payments → name of your backend workflow in Bubble
• api_token → generated in Bubble under Settings > API > Generate private key

Make sure you use the correct version in the URL:

• Development: includes version-test
• Live: does not include version-test

4. Add webhook verification (optional but highly recommended)

To secure your webhook:

1. Generate a Webhook Signing Key in Easytools.
2. Use the Toolbox plugin in Bubble.
3. In your backend workflow (easy_payments), add a Server Script step.
4. Paste in your signing key and compare the computed hash with the x-webhook-signature from Easytools.

If they match, continue the workflow. If not, terminate the workflow immediately.

Note: You will not be able to see the signing key again after generating it, so store it securely.

5. Route webhook events to sub-workflows

Use your main webhook (easy_payments) as a router. Based on the event type, redirect to specific backend workflows:

Examples:

• process_product_assigned
• process_subscription_expired

Only the main webhook should be public. These sub-workflows should remain private.

6. Set up sub-workflows

For process_product_assigned:

• Enable “Ignore privacy rules”
• Manually define parameters to receive from the webhook:
  • subscription_type
  • subscription_one_time
  • is_subscription
  • price
  • custom_id
  • etc.

Steps:

1. (Optional) Send yourself an email for testing.
2. Modify the matching user in your database:
   • Set subscribed = yes if a valid subscription is active.
   • Update other fields like subscription_type, renewal_date, trial_ends_at, etc.
3. Use conditional logic:
   • If subscription_one_time = yes → subscribed = yes
   • If both subscription_one_time and is_subscription are no → subscribed = no

For process_subscription_expired:

• Modify the user:
  • Set subscribed = no
  • Set access_expired = yes
• Optionally send yourself a notification email

7. Handle multiple JSON formats

Bubble expects one consistent JSON structure, but Easytools sends different ones based on the event.

To solve this:

1. Copy all JSON examples from Easytools documentation.
2. Combine them into one unified JSON
3. Go to your easy_payments workflow in Bubble and click “Detect data”.
4. Use Postman to send your combined JSON:
   • Method: POST
   • Paste the webhook URL
   • Body: raw JSON
5. Bubble will recognize the structure. Double-check each field’s type (e.g., number, text, date).

Provided merged JSON file

Here's a combined JSON schema generated by Chris that includes all relevant keys from all Easytools webhook events. This file can be used during detection in Bubble to initialize the webhook endpoint correctly.

Download the combined JSON file.

Make sure to use this file when using Postman to send the test request to Bubble during the “Detect data” step. This ensures that Bubble captures every possible field used across the different Easytools webhook events.

To use the file:

1. Open the attached easytools_merged_webhook.json file.
2. Copy its content into the raw body of your request in Postman.
3. Send the POST request to your webhook detection URL in Bubble.

After sending:

• Bubble will display all the detected fields.
• Review each one and confirm that the data types are correct:
  • Dates should be set as date.
  • Numbers should be number.
  • Text fields should be text.

Once everything looks good, click Save in Bubble to finalize the webhook setup.

8. Match users by email

To assign the webhook to the correct user:

• Have users create an account in your app first.
• Pre-fill the Easytools checkout form with Current User's email.
• In your webhook workflow, find the user using:

Search for Users where email = request.body.customer_email

If the email doesn’t match, Bubble can’t assign the purchase to a user. Force email consistency upfront.

9. Test the full flow

1. Set a test user's subscribed field to no in the Bubble database.
2. Try accessing a protected feature → user is redirected to Easytools checkout.
3. Make a test payment.
4. Back in Bubble:
   • The webhook is received and verified
   • The user’s subscribed field is updated
   • The app detects it and unlocks access

Note: It usually takes 8–10 seconds for the webhook to be processed.

You can either:

• Add a 20-second delay in Easytools’ redirect
• Show a “processing” screen while polling for subscribed = yes

Final notes

• Backend workflows in Bubble are only available on paid plans.
• Always test both one-time and recurring subscriptions.
• Make sure your webhook logic is secure, especially when handling payments.

‍