---
title: "PHP and Laravel Tutorial: Send, Embed and Track a Contract"
description: "Build a Laravel app that sends a contract, embeds the signing ceremony, verifies webhooks on the raw body and downloads the signed PDF."
canonical: "https://signatureapi.com/docs/tutorials/php-laravel"
source: "https://signatureapi.com/docs/tutorials/php-laravel.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:33:13Z"
---

# PHP and Laravel Tutorial: Send, Embed and Track a Contract

Build a Laravel app that sends a contract, embeds the signing ceremony, verifies webhooks on the raw body and downloads the signed PDF.

_Last verified against API version 1.18.0._

This tutorial builds a complete Laravel app with SignatureAPI: your server creates an envelope, the user signs inside your page, a verified webhook reports the result, and your server downloads the signed PDF. It uses Laravel's `Http` client and cache; the SignatureAPI logic sits in one class, `App\Support\SignatureApi`, that you can reuse in any PHP app.

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

- PHP 8.3 and Composer.
- 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. `buildContract()` 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.

```php app/Support/SignatureApi.php
public function buildContract(string $name, string $email, string $userId): array
{
    return [
        'title' => 'Service Agreement',
        'metadata' => ['app_user_id' => $userId],
        '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' => $userId]]],
                'embeddable_in' => [$this->appOrigin],
            ],
        ]],
    ];
}
```

The envelope starts in `processing`, and the ceremony opens only once it is `in_progress`. `createSigningSession()` 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).

```php app/Support/SignatureApi.php
public function createSigningSession(string $name, string $email, string $userId): array
{
    $envelope = $this->api('POST', '/v1/envelopes', $this->buildContract($name, $email, $userId));
    for ($attempt = 0; $envelope['status'] === 'processing' && $attempt < 30; $attempt++) {
        sleep(1);
        $envelope = $this->api('GET', "/v1/envelopes/{$envelope['id']}");
    }
    if ($envelope['status'] !== 'in_progress') {
        throw new ApiException("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 resources/views/index.blade.php
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. `WebhookVerifier::verify()` 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.

```php app/Support/WebhookVerifier.php
public static function verify(string $secret, array $headers, string $rawBody, int $now, int $toleranceSeconds = 300): bool
{
    $lower = array_change_key_case($headers, CASE_LOWER);
    $id = $lower['webhook-id'] ?? '';
    $timestamp = $lower['webhook-timestamp'] ?? '';
    $signatureHeader = $lower['webhook-signature'] ?? '';
    if ($id === '' || $timestamp === '' || $signatureHeader === '') {
        throw new WebhookVerificationException('Missing webhook-id, webhook-timestamp or webhook-signature header');
    }
    if (!ctype_digit($timestamp)) {
        throw new WebhookVerificationException('Invalid webhook-timestamp');
    }
    if (abs($now - (int) $timestamp) > $toleranceSeconds) {
        throw new WebhookVerificationException('Timestamp outside the tolerance window');
    }

    $key = base64_decode(preg_replace('/^whsec_/', '', $secret), true);
    if ($key === false) {
        throw new WebhookVerificationException('Secret is not valid base64');
    }
    $expected = hash_hmac('sha256', "{$id}.{$timestamp}.{$rawBody}", $key, true);

    // The header holds space-separated "v1,<base64>" entries. Any match is enough.
    foreach (explode(' ', $signatureHeader) as $entry) {
        $parts = explode(',', $entry, 2);
        if (count($parts) !== 2 || $parts[0] !== 'v1') {
            continue;
        }
        $candidate = base64_decode($parts[1], true);
        if ($candidate !== false && hash_equals($expected, $candidate)) {
            return true;
        }
    }
    throw new WebhookVerificationException('No matching signature');
}
```

The handler reads the raw body with `$request->getContent()`, 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).

```php app/Http/Controllers/WebhookController.php
public function receive(Request $request): JsonResponse
{
    $rawBody = $request->getContent();
    $webhookId = (string) $request->header('webhook-id');

    try {
        WebhookVerifier::verify(
            (string) config('services.signatureapi.webhook_secret'),
            [
                'webhook-id' => $webhookId,
                'webhook-timestamp' => $request->header('webhook-timestamp'),
                'webhook-signature' => $request->header('webhook-signature'),
            ],
            $rawBody,
            time(),
        );
    } catch (WebhookVerificationException $e) {
        return response()->json(['error' => $e->getMessage()], 400);
    }

    // Retries repeat the same webhook-id for up to 48 hours. Cache::add stores the key only if it is absent.
    // In production these live in your database.
    if (!Cache::add("signatureapi-webhook:{$webhookId}", true, now()->addDays(3))) {
        return response()->json(['duplicate' => true]);
    }

    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    $envelopeId = $event['data']['envelope_id'] ?? null;
    $record = Cache::get("contract:{$envelopeId}", ['status' => 'unknown', 'events' => []]);
    $record['events'][] = $event['type'];
    if ($event['type'] === 'envelope.completed') {
        $record['status'] = 'completed';
    }
    Cache::put("contract:{$envelopeId}", $record, now()->addDays(3));
    Log::info("webhook {$event['type']} for envelope {$envelopeId}");

    return response()->json(['received' => true]);
}
```

The webhook route sits outside CSRF protection: SignatureAPI can't send a CSRF token, and the signature is the authentication.

## 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. `downloadSignedPdf()` 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.

```php app/Support/SignatureApi.php
public function downloadSignedPdf(string $envelopeId): string
{
    $envelope = $this->api('GET', "/v1/envelopes/{$envelopeId}");
    if ($envelope['status'] !== 'completed' || empty($envelope['deliverable'])) {
        throw new NotReadyException("Envelope is {$envelope['status']}. The signed PDF exists once it is completed.");
    }
    $deliverable = $this->api('GET', "/v1/deliverables/{$envelope['deliverable']['id']}");
    if ($deliverable['status'] !== 'generated') {
        throw new NotReadyException("Deliverable is {$deliverable['status']}. Try again in a few seconds.");
    }

    return Http::timeout(60)->get($deliverable['url'])->throw()->body();
}
```

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
composer install
cp .env.example .env && php artisan key:generate
export SIGNATUREAPI_KEY=YOUR_API_KEY            # your test key
export SIGNATUREAPI_WEBHOOK_SECRET=whsec_YOUR_SECRET
export APP_ORIGIN=http://localhost:8000
php artisan serve
```

Open <http://localhost:8000>, 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
php artisan test
```

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.
