Skip to content

Best practices

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.

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.
  3. The worker saves the envelope id with the order. The envelope starts in processing; its outcome arrives later as an event.

Receiving:

  1. A webhook endpoint verifies the signature, stores the event in an inbox table keyed by event id, enqueues it and answers 200. It does nothing else.
  2. An event worker takes the event, reads the envelope from the API, and updates the order. See Idempotent webhook processing.
  3. 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:

  • 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 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.
  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.