---
title: "Python Tutorial with Django and Flask"
description: "Build a Python app with Flask or Django that sends a contract, embeds the signing ceremony, verifies webhooks and downloads the signed PDF."
canonical: "https://signatureapi.com/docs/tutorials/python"
source: "https://signatureapi.com/docs/tutorials/python.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:33:13Z"
---

# Python Tutorial with Django and Flask

Build a Python app with Flask or Django that sends a contract, embeds the signing ceremony, verifies webhooks and downloads the signed PDF.

_Last verified against API version 1.18.0._

This tutorial builds a complete Python app with SignatureAPI, in two variants: Flask and Django. Your server creates an envelope, the user signs inside your page, a verified webhook reports the result, and your server downloads the signed PDF. The API client in `signatureapi.py` uses only the standard library and is the same in both variants; only the routes differ.

The app has one page and four server routes:

- `GET /`: a form and the ceremony iframe.
- `POST /api/contracts`: creates the envelope and returns the ceremony URL.
- `GET /api/contracts/{id}`: reads the envelope status on the server.
- `GET /api/contracts/{id}/signed.pdf`: streams the signed PDF.
- `POST /webhooks/signatureapi`: receives events and verifies each one.

## Before you start

- Python 3.10 or newer.
- A test API key (`key_test_...`) from the [Dashboard](https://dashboard.signatureapi.com). Test envelopes are free, send no emails and are not legally binding. See [Test mode](https://signatureapi.com/docs/api/test-mode).
- To receive webhooks on your machine, a public tunnel to your local port and a webhook endpoint for it in [Dashboard > Settings > Webhooks](https://dashboard.signatureapi.com/settings/webhooks). Copy the endpoint's signing secret. See [Set Up Webhooks](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks).

## 1. Create the envelope on your server

The API key stays on your server. `build_contract()` builds the envelope with three recipient options for embedding:

- `delivery_type: "none"`: SignatureAPI doesn't email the signed PDF, because your app shows the result.
- [`custom` authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom): your app already signed the user in, so the ceremony URL comes back in the response instead of an email.
- `embeddable_in`: the origin allowed to show the ceremony in an iframe.

```python signatureapi.py
def build_contract(name: str, email: str, user_id: str, app_origin: str) -> dict[str, Any]:
    """Envelope for an embedded ceremony: custom authentication, embeddable_in, no email delivery."""
    return {
        "title": "Service Agreement",
        "metadata": {"app_user_id": user_id},
        "documents": [{
            "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
            "format": "pdf",
            "places": [{"key": "client_signature", "type": "signature", "recipient_key": "client"}],
            "fixed_positions": [{"place_key": "client_signature", "page": 1, "top": 172, "left": 210}],
        }],
        "recipients": [{
            "key": "client",
            "type": "signer",
            "name": name,
            "email": email,
            "delivery_type": "none",
            "ceremony": {
                "authentication": [{"type": "custom", "provider": "Acme Corp Portal", "data": {"user_id": user_id}}],
                "embeddable_in": [app_origin],
            },
        }],
    }
```

The envelope starts in `processing`, and the ceremony opens only once it is `in_progress`. `create_signing_session()` reads the envelope once a second until then and returns the ceremony URL from that read. Every read returns a [new URL for the same ceremony](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#url-validity).

```python signatureapi.py
def create_signing_session(config: Config, name: str, email: str, user_id: str) -> dict[str, str]:
    """Creates the envelope and waits until it is in_progress.

    The ceremony opens only after the envelope leaves `processing`. Each read returns a fresh
    ceremony URL for the same ceremony.
    """
    envelope = api(config, "POST", "/v1/envelopes", build_contract(name, email, user_id, config.app_origin))
    for _ in range(30):
        if envelope["status"] != "processing":
            break
        time.sleep(1)
        envelope = api(config, "GET", f"/v1/envelopes/{envelope['id']}")
    if envelope["status"] != "in_progress":
        raise ApiError(502, {"detail": f"Envelope is {envelope['status']}, not ready for signing"})
    return {"envelopeId": envelope["id"], "ceremonyUrl": envelope["recipients"][0]["ceremony"]["url"]}
```

## 2. Embed the ceremony

The page adds `embedded=true` and `event_delivery=message` to the ceremony URL and loads it in an iframe. It accepts [ceremony events](https://signatureapi.com/docs/embedded/ceremony-events) only from `https://sign.signatureapi.com` and from its own iframe.

```javascript templates/index.html
const CEREMONY_ORIGIN = 'https://sign.signatureapi.com';
const iframe = document.getElementById('signatureapi-ceremony');
const status = document.getElementById('status');
let envelopeId = null;

document.getElementById('start').addEventListener('submit', async (event) => {
  event.preventDefault();
  const form = new FormData(event.target);
  const response = await fetch('/api/contracts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: form.get('name'), email: form.get('email') }),
  });
  const body = await response.json();
  if (!response.ok) { status.textContent = body.error; return; }
  envelopeId = body.envelopeId;
  // Both query parameters are required for an embedded ceremony.
  const src = new URL(body.ceremonyUrl);
  src.searchParams.set('embedded', 'true');
  src.searchParams.set('event_delivery', 'message');
  iframe.src = src.toString();
  iframe.classList.remove('hidden');
});

window.addEventListener('message', async (event) => {
  // Accept messages only from the ceremony iframe.
  if (event.origin !== CEREMONY_ORIGIN || event.source !== iframe.contentWindow) return;
  if (event.data.type === 'ceremony.completed') {
    iframe.classList.add('hidden');
    // The browser event is a UI signal. Confirm on your server before you act on it.
    const response = await fetch(`/api/contracts/${envelopeId}`);
    const body = await response.json();
    status.textContent = `Thanks! Envelope status: ${body.status}`;
    // The signed PDF is ready a few seconds after completion. Your server streams it (step 5).
    const download = document.getElementById('download');
    download.href = `/api/contracts/${envelopeId}/signed.pdf`;
    download.classList.remove('hidden');
  } else if (event.data.type === 'ceremony.canceled') {
    status.textContent = 'Signing canceled. You can start again any time.';
  } else if (event.data.type === 'ceremony.failed') {
    status.textContent = `Signing failed: ${event.data.error_message}`;
  }
});
```

A `ceremony.completed` message is a signal for your UI, not proof of signing: the page asks your server for the envelope status before it shows the result. To send the signer to the ceremony page instead of embedding it, open the URL without `embedded=true` and set a [redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url) for the way back.

## 3. Verify webhooks on the raw body

SignatureAPI signs every delivery with the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) scheme. `verify_webhook()` computes an HMAC-SHA256 over `webhook-id.webhook-timestamp.body` with your signing secret, compares it in constant time with each `v1` entry of `webhook-signature`, and rejects timestamps more than 5 minutes off. It runs on the exact bytes received: parsing and re-serializing the JSON changes them and breaks the signature.

```python signatureapi.py
def verify_webhook(secret: str, headers: Mapping[str, str], raw_body: bytes, *,
                   now: int | None = None, tolerance_seconds: int = 300) -> dict:
    """Standard Webhooks verification. Returns the parsed event or raises WebhookError."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not (msg_id and timestamp and signatures):
        raise WebhookError("Missing webhook headers")
    now = int(time.time()) if now is None else now
    if not timestamp.isdigit() or abs(now - int(timestamp)) > tolerance_seconds:
        raise WebhookError("Webhook timestamp outside the tolerance window")
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return json.loads(raw_body)
    raise WebhookError("Invalid webhook signature")
```

The handler reads the raw body (`request.get_data()` in Flask, `request.body` in Django), verifies it, and skips any `webhook-id` it has already processed. Deliveries are retried for up to 48 hours and can repeat, so in production store the ids with a unique index. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

```python Flask
@app.post("/webhooks/signatureapi")
def webhook():
    raw = request.get_data()
    headers = {k.lower(): v for k, v in request.headers.items()}
    try:
        event = verify_webhook(config.webhook_secret, headers, raw)
    except WebhookError as error:
        return jsonify(error=str(error)), 400
    webhook_id = headers["webhook-id"]
    if webhook_id in seen_webhook_ids:
        return jsonify(duplicate=True), 200
    seen_webhook_ids.add(webhook_id)
    envelope_id = event.get("data", {}).get("envelope_id")
    record = contracts.setdefault(envelope_id, {"status": "unknown", "events": []})
    record["events"].append(event["type"])
    if event["type"] == "envelope.completed":
        record["status"] = "completed"
    app.logger.info("webhook %s for envelope %s", event["type"], envelope_id)
    return jsonify(received=True), 200
```

```python Django
@csrf_exempt  # The sender cannot present a CSRF token. The signature is the authentication.
@require_POST
def webhook(request):
    raw = request.body
    headers = {k.lower(): v for k, v in request.headers.items()}
    try:
        event = verify_webhook(settings.SIGNATUREAPI_WEBHOOK_SECRET, headers, raw)
    except WebhookError as error:
        return JsonResponse({"error": str(error)}, status=400)
    webhook_id = headers["webhook-id"]
    if webhook_id in seen_webhook_ids:
        return JsonResponse({"duplicate": True})
    seen_webhook_ids.add(webhook_id)
    envelope_id = event.get("data", {}).get("envelope_id")
    record = contracts.setdefault(envelope_id, {"status": "unknown", "events": []})
    record["events"].append(event["type"])
    if event["type"] == "envelope.completed":
        record["status"] = "completed"
    print(f"webhook {event['type']} for envelope {envelope_id}")
    return JsonResponse({"received": True})
```

## 4. Confirm the status

`GET /api/contracts/{id}` reads the envelope with [`GET /v1/envelopes/{id}`](https://signatureapi.com/docs/api/resources/envelopes/get) and returns its status, together with the webhook events stored for it. The page calls it after the ceremony finishes.

## 5. Download the signed PDF

When the envelope completes, SignatureAPI generates the [deliverable](https://signatureapi.com/docs/api/resources/deliverables/object): the signed PDF with its audit log. `download_signed_pdf()` reads the envelope, gets its deliverable, and downloads the file from the deliverable's `url`. That URL is pre-signed and expires after 1 hour, so the function asks for a fresh one on each download instead of storing it.

```python signatureapi.py
def download_signed_pdf(config: Config, envelope_id: str) -> bytes:
    """Downloads the signed PDF of a completed envelope.

    The deliverable URL is pre-signed and expires after 1 hour, so fetch a fresh one each time
    instead of storing it. It needs no API key.
    """
    envelope = api(config, "GET", f"/v1/envelopes/{envelope_id}")
    if envelope["status"] != "completed" or not envelope.get("deliverable"):
        raise NotReadyError(f"Envelope is {envelope['status']}. The signed PDF exists once it is completed.")
    deliverable = api(config, "GET", f"/v1/deliverables/{envelope['deliverable']['id']}")
    if deliverable["status"] != "generated":
        raise NotReadyError(f"Deliverable is {deliverable['status']}. Try again in a few seconds.")
    with urllib.request.urlopen(deliverable["url"], timeout=60) as response:
        return response.read()
```

Until the deliverable is generated, the route answers `409` and the page can try again a few seconds later. To store the PDF as soon as it exists, call the same function when your webhook handler receives `deliverable.generated`.

## Run it

```shell
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
export SIGNATUREAPI_KEY=YOUR_API_KEY            # your test key
export SIGNATUREAPI_WEBHOOK_SECRET=whsec_YOUR_SECRET
flask --app app run            # Flask, in tutorials/python-flask
python manage.py runserver     # Django, in tutorials/python-django
```

Open <http://localhost:5000> (Flask) or <http://localhost:8000> (Django), keep the sample name and email, and select **Start signing**. After you sign, the page shows `Thanks! Envelope status: completed` and a link to the signed PDF.

## Test it

```shell
python -m unittest discover -s tests -t .   # Flask
python manage.py test                       # Django
```

The tests check the webhook verifier against a fixed test vector, then run the app against a local mock API: the envelope payload, the `422` path, webhook acceptance, tampering and duplicates, and the PDF download. With `SIGNATUREAPI_KEY` set to a test key, two more tests run against the API: one creates an embedded envelope and waits for `in_progress`, the other completes an envelope with an [automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer) and downloads its signed PDF.

## Troubleshooting

- **The iframe is blank or refuses to load.** `embeddable_in` must match your page's origin exactly (scheme, host and port), and the URL needs `embedded=true`.
- **The ceremony asks the signer to try again later.** The envelope was still `processing`. Show the URL only after the envelope is `in_progress`, as step 1 does.
- **No `message` events arrive.** Add `event_delivery=message` to the URL and check that the origin filter uses `https://sign.signatureapi.com`.
- **Every webhook fails verification.** Each endpoint has its own signing secret, and a proxy or body parser may have changed the body before verification.
- **The download returns `409`.** The deliverable is still being generated. Wait for `deliverable.generated` or try again in a few seconds.

## Next steps

- [Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app): the full request flow and every ceremony option.
- [Webhooks](https://signatureapi.com/docs/api/webhooks): events, retries and source IPs.
- [Go-live checklist](https://signatureapi.com/docs/api/guides/go-live-checklist): what to check before you switch to a live key.
