Cookbook
Reconcile envelope status when webhooks are missed
Run a periodic job that checks every envelope your system still considers open against the API and fixes any status a missed webhook left stale.
Webhooks are the fast path. A periodic job is the safety net for when your endpoint was down for longer than the 48 hours SignatureAPI retries an event.
The job reads the envelopes your own database still marks as open, asks the API for each one’s current status, and updates your records. It writes the same values a webhook handler would, so it’s safe to run alongside one.
const API = "https://api.signatureapi.com/v1";
const headers = { "X-API-Key": process.env.SIGNATUREAPI_KEY };
// Run every 15 minutes or hourly from your scheduler.
export async function reconcile(db) {
const open = await db.openEnvelopeIds(); // rows whose status is processing or in_progress
for (const id of open) {
const res = await fetch(`${API}/envelopes/${id}`, { headers });
if (res.status === 429) break; // rate limited: continue on the next run
if (!res.ok) continue;
const envelope = await res.json();
if (envelope.status !== "processing" && envelope.status !== "in_progress") {
await db.markEnvelope(id, envelope.status, envelope.completed_at);
}
}
}import os
import requests
API = "https://api.signatureapi.com/v1"
HEADERS = {"X-API-Key": os.environ["SIGNATUREAPI_KEY"]}
# Run every 15 minutes or hourly from your scheduler.
def reconcile(db):
for envelope_id in db.open_envelope_ids(): # rows whose status is processing or in_progress
res = requests.get(f"{API}/envelopes/{envelope_id}", headers=HEADERS)
if res.status_code == 429:
break # rate limited: continue on the next run
if not res.ok:
continue
envelope = res.json()
if envelope["status"] not in ("processing", "in_progress"):
db.mark_envelope(envelope_id, envelope["status"], envelope["completed_at"])db.openEnvelopeIds and db.markEnvelope stand for your own data access. A final status is completed, failed or canceled. For a completed envelope, the same job can then fetch its deliverable if you haven’t stored it.
- One request per open envelope. Each call counts toward your rate limit. Spread a large backlog over several runs, as the
429branch does. - Starting from the API instead. To discover envelopes you have no record of, list envelopes with the
statusortopicfilter and followlinks.nextthrough the pages. See pagination. - Missed events. The events endpoint lists past events, which helps you replay what an endpoint missed.