Skip to main content

Embedded or BySide: choosing where your users sign

· 4 min read
Julien Jenoudet
Julien Jenoudet
CEO of IgniSign

When a new flow in your product needs a signature (an onboarding contract, a mandate, a consent), the first technical decision is not the signature level or the document format. It is where the signer will be when they sign. For documents, IgniSign gives you two answers: embedded, where the signing interface runs in an iframe inside your page, and BySide, where the signer opens an IgniSign-hosted signing page from a link. Both start from the same signature request. This post is about picking one.

What stays the same​

Whichever mode you choose, your backend does the same work. It creates a signature request through the API (the one-call signature request is enough for a first flow), and it listens to webhooks to learn when the signature is complete.

The signer sees the same hosted IgniSign signer interface in both modes. It is brandable with your logo, colour palette, support email and language.

So the decision comes down to two things: your front end, and who the signer is.

Embedded: the signer is already your user​

In embedded mode, your page loads the signing interface in an iframe. The iframe reports to your page through postMessage, so your front end can react when the signer finishes: close the modal, move to the next step, show a confirmation.

Choose embedded when:

  • The signer is logged into your product at the moment of signing: a user completing onboarding, accepting terms for a new plan, or signing a mandate in the middle of a checkout.
  • Signing is one step of a longer flow, and leaving the page would break it. Every redirect is a place where users drop off.
  • You want the step to look like the rest of your product, not like a separate tool.

What it costs you is front-end work. You host the iframe, listen for its messages, and decide what your page does when the signer finishes or walks away. Your Content Security Policy also has to allow the IgniSign signing origin as a frame source.

BySide: the signer is somewhere else​

In BySide mode, the signer signs on an IgniSign-hosted page reached through a link. Your page does not host anything, and your backend learns the outcome from the webhook.

Choose BySide when:

  • The signer has no account in your product: a counterparty, a guarantor, a second director, your customer's customer.
  • The signature happens later or on another device, outside the session that created the request.
  • You want a first version live with very little front-end work, and the signer leaving your page is acceptable.

What it costs you is the context switch. For an outside party who was never in your product, that is fine. For your own users in the middle of a flow, it is a real cost, and it is usually the reason teams move a step to embedded later.

Make the webhook your source of truth​

In both modes, treat the webhook as the record of what happened, not the browser. The iframe message tells your front end that the signer is done; the webhook tells your backend. A user can close the tab one second after signing, and your state should still be correct.

Three habits help:

  • Update your own records from the webhook, and check the verification token that comes with each delivery.
  • Subscribe only to the topics your flow needs.
  • Make your handler accept the same event twice. If your endpoint was down during a delivery, the event log shows it and lets you resend it manually.

A three-question test​

  1. Is the signer logged into your product when they sign? If yes, start with embedded.
  2. Would leaving the page break the flow? If yes, embedded.
  3. Is the signer an outside party, or signing later from another device? BySide.

If the answers split, build BySide first. It needs the least front-end code and gives you a complete loop (signature request, signature, webhook) in your development environment. Then move the steps where your own users sign into the iframe, one flow at a time. The backend you wrote for BySide does not change.

A third mode, Bare, covers flows where your application keeps the document and only a hash goes through the signing step. That is a different decision, and the subject of another post.