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:
- 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.
- 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. - The worker saves the envelope
idwith the order. The envelope starts inprocessing; its outcome arrives later as an event.
Receiving:
- A webhook endpoint verifies the signature, stores the event in an inbox table keyed by event
id, enqueues it and answers200. It does nothing else. - An event worker takes the event, reads the envelope from the API, and updates the order. See Idempotent webhook processing.
- 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,5XXand 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
4XXerrors: 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:
- 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. - 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.