---
title: "Embed Signing in a Bubble App"
description: "Create SignatureAPI envelopes from Bubble with the API Connector, show the signing ceremony inside your app, and receive signing events in a backend workflow."
canonical: "https://signatureapi.com/docs/integrations/bubble"
source: "https://signatureapi.com/docs/integrations/bubble.md"
last_verified_api_version: "1.18.0"
---

# 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.

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store). 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](https://signatureapi.com/docs/api/resources/uploads/create) 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](https://manual.bubble.io/core-resources/api/the-api-connector)).

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](https://forum.bubble.io/t/new-feature-api-connector-improvements/7625)).

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](https://manual.bubble.io/core-resources/api/the-api-connector/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:

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Header**: `X-API-Key: YOUR_API_KEY`

   Store the key in Bubble's secret or credential storage when it has one.
4. **Header**: `Content-Type: application/json`
5. **Body (raw JSON)**:

   ```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](https://signatureapi.com/docs/embedded/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:

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **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](https://manual.bubble.io/core-resources/bubble-elements/element-properties/web-element-properties/visual-element-properties/html)).

## 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](https://manual.bubble.io/core-resources/api/the-bubble-api/the-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](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated) 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](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in test mode with the workflow URL. Subscribe to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, and add the `bubble` topic. The [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) 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](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download.

The same event can arrive twice, so skip a user who already shows as signed. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

## Related

- [Embed in a web app](https://signatureapi.com/docs/embedded/web-app): origins, events and troubleshooting.
- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).

### Example: Embedded signer

The ceremony opens inside your Bubble app.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/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"
        ]
      }
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement - Jane Doe",
  "label": null,
  "message": "Please review and sign the service agreement.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ]
  },
  "metadata": {
    "source": "bubble",
    "user_id": "1700000000000x123456789"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "signer_signature"
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "signer",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "Acme App",
            "data": {
              "user_id": "1700000000000x123456789"
            }
          }
        ],
        "embeddable_in": [
          "https://acme.bubbleapps.io"
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXMiOiJzZXNfMWNoSUVrTE9tdFVNRG9hTDhwOUEifQ.c2lnbmF0dXJl",
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "no_code",
    "bubble"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "recipients[0].email must be a valid email address."
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
