---
title: "Reconcile envelope status when webhooks are missed"
description: "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."
canonical: "https://signatureapi.com/docs/cookbook/reconcile-status"
source: "https://signatureapi.com/docs/cookbook/reconcile-status.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:17:27Z"
---

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

_Last verified against API version 1.18.0._

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.

```javascript Node.js
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);
    }
  }
}
```

```python Python
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](https://signatureapi.com/docs/api/resources/deliverables/list) if you haven't stored it.

- **One request per open envelope.** Each call counts toward your [rate limit](https://signatureapi.com/docs/api/rate-limiting). Spread a large backlog over several runs, as the `429` branch does.
- **Starting from the API instead.** To discover envelopes you have no record of, [list envelopes](https://signatureapi.com/docs/api/resources/envelopes/list) with the `status` or `topic` filter and follow `links.next` through the pages. See [pagination](https://signatureapi.com/docs/api/pagination).
- **Missed events.** The [events endpoint](https://signatureapi.com/docs/api/resources/events/all) lists past events, which helps you replay what an endpoint missed.

## Related

- [Webhooks](https://signatureapi.com/docs/api/webhooks)
- [Envelope lifecycle](https://signatureapi.com/docs/api/resources/envelopes/lifecycle)
- [Get an envelope](https://signatureapi.com/docs/api/resources/envelopes/get)
