How to add e-signatures to your app: API, embedded signing and webhooks

If your product involves agreements, such as onboarding contracts, rental applications, consent forms or order forms, sending users off to another site to sign is a leaky step in your funnel. Embedding signing keeps them in your product, and a decent API means you can do it in an afternoon. This guide walks through the whole flow with Parapho; the same concepts apply to most e-signature APIs.

The flow at a glance

1. Template: upload your PDF once and place fields for each signer role.
2. Envelope: your server creates an envelope from the template for a specific person.
3. Embed: your page shows that person's signing link in a frame.
4. Events: the browser tells your page when they finish; a signed webhook tells your server.
5. Download: fetch the sealed PDF and store it, or link to it.

1. Build a template

In the app, upload the PDF and drag fields onto it: signature, initials, date, name, text, number, checkbox, dropdown and more. Give each field a role, such as Client or Company. You can also upload documents and create templates over the API. Templates mean your code sends only who signs, never where fields go.

2. Get API keys and allow your origin

Under Settings & API, create an API key. Start with a sk_test_ key: test envelopes are watermarked, no email is sent and nothing is billed. Keys are shown once and stored only as hashes, so put yours in an environment variable.

Then add each site that will host the signing frame under Embedded signing → Allowed origins, for example https://app.yourcompany.com. Origins are scheme, host and port only. Until an origin is added, browsers refuse to show the frame.

3. Create the envelope on your server

Set send_email: false so Parapho doesn't email the signer, and send an Idempotency-Key so a retried request can't create a duplicate.

import { Parapho } from '@parapho/node';

const parapho = new Parapho({ apiKey: process.env.PARAPHO_API_KEY });

const envelope = await parapho.envelopes.create({
  template_id: 'tpl_nda',
  send_email: false,              // we'll embed signing instead
  recipients: [
    { role: 'Client', name: 'Ada Lovelace', email: 'ada@example.com' },
  ],
}, { idempotencyKey: `nda-${dealId}` });

const embedUrl = envelope.recipients[0].embed_url;

Or in Python:

import os
from parapho import Parapho

parapho = Parapho(api_key=os.environ["PARAPHO_API_KEY"])

envelope = parapho.envelopes.create(
    "tpl_nda",
    [{"role": "Client", "name": "Ada Lovelace", "email": "ada@example.com"}],
    send_email=False,
    idempotency_key=f"nda-{deal_id}",
)

You can also prefill fields (editable or read-only), attach your own metadata such as a customer ID, and choose sequential or parallel signing for several recipients.

4. Show signing in your page

Load the embed script and drop in the web component. The frame resizes itself to the document.

<script src="https://app.parapho.com/sdk/embed.js"></script>

<parapho-signing src="EMBED_URL"></parapho-signing>

<script>
  document.querySelector('parapho-signing')
    .addEventListener('parapho:completed', (e) => {
      showThankYou(e.detail.envelopeId);
    });
</script>

In React:

import { ParaphoSigning } from '@parapho/react';

export function SignContract({ embedUrl }) {
  return (
    <ParaphoSigning
      url={embedUrl}
      onComplete={({ envelopeId }) => router.push(`/done/${envelopeId}`)}
      onDecline={() => toast('The signer declined')}
    />
  );
}

5. Trust the webhook, not the browser

Browser events are great for UX, but a user can close the tab or tamper with client-side code. Update your database from the webhook instead. Every webhook carries a Parapho-Signature header (HMAC-SHA256 with a timestamp), and the SDKs verify it in one line:

import express from 'express';
import { verifyWebhook } from '@parapho/node';

app.post('/webhooks/parapho', express.raw({ type: '*/*' }), (req, res) => {
  const event = verifyWebhook(
    req.body,                                  // the raw body
    req.get('parapho-signature'),
    process.env.PARAPHO_WEBHOOK_SECRET,
  );
  if (event.event === 'envelope.completed') {
    markContractSigned(event.data.id);
  }
  res.sendStatus(200);
});

The events you'll use most:

You can register up to 10 webhook endpoints per workspace, each with its own event filter and secret. Failed deliveries are retried automatically for about a day, and the delivery log lets you inspect and resend any event.

6. Download the sealed PDF

Once complete, GET /api/v1/envelopes/:id/download returns the flattened, digitally signed PDF with its certificate of completion. You can also read every field value as JSON, which is handy for pushing form answers into your CRM. Store the final_sha256 alongside it so you can prove later that the file is unchanged.

Going live

• Swap your sk_test_ key for a live key.
• Add your production origin to the allowed origins (https only).
• Point a webhook endpoint at production and store its secret.
• Handle envelope.declined and envelope.expired, not just the happy path.

API pricing is $0.02 per completed envelope, with the first 100 free every month and no minimum. The developer docs have the full API reference, more recipes and a go-live checklist, or you can get API keys now.