Skip to content

Databases and app builders

Embed Signing in a Bubble App

Create SignatureAPI envelopes from Bubble with the API Connector, show the signing ceremony inside your app, and receive signing events in a backend workflow.

Bubble’s own API Connector plugin calls the SignatureAPI REST API, so no SignatureAPI plugin is needed. One call creates the envelope, an HTML element shows the ceremony inside your page, and a backend workflow receives the result.

Before you start

  • A SignatureAPI test API key (it starts with key_test_).
  • The document you send, at a URL on a supported host. Files you upload to Bubble live on *.cdn.bubble.io, which is a supported host, so a Bubble file URL works as the document url. Or upload to SignatureAPI first.

Send the envelope

1

Add the API and the key

In the API Connector, add a new API. Under Shared headers for all calls, add the header X-API-Key with your key and check Private, so the value isn’t visible client-side (Bubble manual).

2

Add the call

Add a call named Create envelope, set Use as to Action, the method to POST and the URL to https://api.signatureapi.com/v1/envelopes. Paste the JSON body below. Bubble marks a dynamic value in a JSON body with angle brackets, such as <name> (Bubble forum announcement).

3

Initialize the call

Click Initialize call. Bubble needs it before the call can be used, and it reads the response to create a typed field for each value (adding calls). Use a test key and sample values, since this sends a real test envelope.

Bubble HTTP request step

Settings for the "Embedded signer" request.

SettingValue
Method POST
URL https://api.signatureapi.com/v1/envelopes
Header X-API-Key: YOUR_API_KEY

Store the key in Bubble's secret or credential storage when it has one.

Header Content-Type: application/json
Body (raw JSON)The JSON below.
Body (raw JSON)
{
  "title": "Service Agreement - Jane Doe",
  "message": "Please review and sign the service agreement.",
  "metadata": {
    "source": "bubble",
    "user_id": "1700000000000x123456789"
  },
  "topics": [
    "no_code",
    "bubble"
  ],
  "documents": [
    {
      "key": "service_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "signer_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "signer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme App",
            "data": {
              "user_id": "1700000000000x123456789"
            }
          }
        ],
        "embeddable_in": [
          "https://acme.bubbleapps.io"
        ]
      }
    }
  ]
}

The recipient’s authentication is custom, which lets the app, not an email link, deliver the ceremony. embeddable_in lists the origins allowed to show it in an iframe: your https://acme.bubbleapps.io address and your custom domain if you have one. See Embed in a web app. The bubble topic lets an endpoint receive only these envelopes. Bubble’s manual says the body is client safe, so keep secrets out of it.

Show the ceremony

The ceremony opens once the envelope is in_progress, and the create response arrives while it is still processing. Read the envelope until its status changes before you show recipients[0].ceremony.url.

1

Add a Data call

Add a second call, Get envelope, with Use as set to Data, the method GET and the URL https://api.signatureapi.com/v1/envelopes/[envelope_id]. Bubble marks a dynamic part of a URL with square brackets.

Bubble HTTP request step

Settings for the "Completed envelope" request.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56
Header X-API-Key: YOUR_API_KEY

Store the key in Bubble's secret or credential storage when it has one.

2

Wait for in_progress

Save the new envelope id on your data, then re-run the Get envelope call, for example on a timer, until its status is in_progress.

3

Show the iframe

Add an HTML element and check Display as iFrame, which runs the HTML as an independent web page. In its HTML property, use Insert dynamic data to put the ceremony URL in an iframe tag with src set to recipients[0].ceremony.url (HTML element).

Get the result back

Bubble backend workflows can be exposed as API endpoints. In Settings > API, check Enable Workflow API and backend workflows, create an API workflow and check Expose as a public API workflow. Its URL is https://appname.bubbleapps.io/api/1.1/wf/workflow_name, or the same path on your own domain (Workflow API).

1

Allow calls without a Bubble login

In the API workflow’s settings, set the authentication to None required. SignatureAPI calls the workflow without a Bubble user or API key, and this option lets any client trigger it.

2

Detect the event data

Click Detect data, then send a POST with the example deliverable.generated payload from Deliverable events to the workflow’s URL with /initialize added at the end. Bubble defines the workflow’s parameters from that request.

3

Register the URL in SignatureAPI

In the Dashboard, add a webhook endpoint in test mode with the workflow URL. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the bubble topic. The envelope.completed event comes earlier, while the PDF may still be generating, so use it only to update a status.

4

Read the envelope before you act

None required lets any client run the workflow, so call Get envelope with the envelope id from data.envelope_id first. Act on the response: deliverable.status is generated, metadata.user_id names your user, and deliverable.url downloads the signed PDF. That link expires after an hour. If your account uses authenticated deliverable URLs, send your API key with the download.

The same event can arrive twice, so skip a user who already shows as signed. See Webhooks.