---
title: "Reference Architecture"
description: "Scale a SignatureAPI integration: queue envelope creation, absorb webhooks in a durable inbox, retry with backoff and park failures in a dead-letter queue."
canonical: "https://signatureapi.com/docs/api/guides/best-practices/architecture"
source: "https://signatureapi.com/docs/api/guides/best-practices/architecture.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:44Z"
---

# Reference Architecture

Scale a SignatureAPI integration: queue envelope creation, absorb webhooks in a durable inbox, retry with backoff and park failures in a dead-letter queue.

_Last verified against API version 1.18.0._

Calling the API straight from a request handler works for a few envelopes. At volume, rate limits, timeouts and webhook bursts start to matter, and a queue between your app and SignatureAPI keeps each part simple. This page describes one layout that holds up in production. Use the parts you need.

## The Pipeline

Your system has two flows: one that sends envelopes and one that receives events.

**Sending:**

1. Your app records the request in its database, for example "send contract for order 1001", and enqueues a job. It doesn't call SignatureAPI itself.
2. A worker takes the job and creates the envelope with a topic built from the order, such as `order_1001`, so a retry never creates a duplicate. See [Retry envelope creation without duplicates](https://signatureapi.com/docs/api/guides/how-to/retries-and-errors#retry-envelope-creation-without-duplicates).
3. The worker saves the envelope `id` with the order. The envelope starts in `processing`; its outcome arrives later as an event.

**Receiving:**

4. A webhook endpoint [verifies the signature](https://signatureapi.com/docs/api/guides/how-to/verify-webhooks), stores the event in an inbox table keyed by event `id`, enqueues it and answers `200`. It does nothing else.
5. An event worker takes the event, reads the envelope from the API, and updates the order. See [Idempotent webhook processing](https://signatureapi.com/docs/api/guides/best-practices/idempotent-webhooks).
6. On `deliverable.generated`, a worker downloads the signed documents into your storage.

## Retries and Dead Letters

Give every job a retry policy that matches the [error groups](https://signatureapi.com/docs/api/guides/how-to/retries-and-errors#which-errors-to-retry):

- **`429`, `5XX` and timeouts:** retry with exponential backoff, starting at 1 second, for about 5 attempts.
- **"Wait" errors**, such as `deliverable-not-ready`: retry later, or drop the job and let the matching event start it again.
- **Other `4XX` errors:** don't retry. The request is wrong and fails the same way every time.

A job that runs out of attempts, or fails with a non-retryable error, moves to a dead-letter queue with the request, the response status and the problem `type`. Alert on that queue. After you fix the cause, for example a recipient's email address, put the job back on the main queue.

## Stay Under the Rate Limit

An API key allows 10 requests per second by default, with bursts of up to 10. Cap the concurrency of every worker that calls the API so that together they stay below that. See [Rate Limiting](https://signatureapi.com/docs/api/rate-limiting) for the limits and how to raise them.

## Reconcile Once a Day

Events can be missed, for example when your endpoint was down longer than the retry window. A daily job closes the gap:

1. Page through `GET /v1/events`, newest first, until you reach events already in your inbox table. Pass each new one through the event worker. See [Pagination](https://signatureapi.com/docs/api/pagination).
2. For orders whose envelope is still not final after the time you expect, fetch the envelope and update the order from its `status`.

## Keep Test and Live Apart

Run the same pipeline in each environment with its own key: a test key in development and staging, a live key in production. Each mode has its own envelopes and webhook endpoints, so register an endpoint per environment. See [Test Mode](https://signatureapi.com/docs/api/test-mode).
