---
title: "Idempotent Webhook Processing"
description: "Process every SignatureAPI webhook event exactly once: deduplicate by event id, handle events out of order, and recover events your endpoint missed."
canonical: "https://signatureapi.com/docs/api/guides/best-practices/idempotent-webhooks"
source: "https://signatureapi.com/docs/api/guides/best-practices/idempotent-webhooks.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:44Z"
---

# Idempotent Webhook Processing

Process every SignatureAPI webhook event exactly once: deduplicate by event id, handle events out of order, and recover events your endpoint missed.

_Last verified against API version 1.18.0._

SignatureAPI delivers each webhook event at least once. A delivery is retried when your endpoint answers with a non-`2XX` status, times out or can't be reached, so the same event can arrive more than once. Events can also arrive out of order. A handler that runs its side effects on every delivery sends two emails, or marks a contract signed twice.

The fix is a handler that gives the same result however many times, and in whatever order, events arrive.

## Deduplicate by Event ID

Every delivery of one event carries the same event `id` (`evt_...`) in the payload. Use it as the deduplication key:

1. [Verify the signature](https://signatureapi.com/docs/api/guides/how-to/verify-webhooks) on the raw body.
2. Insert the event `id` into a table where it is the primary key or has a unique index.
3. If the insert fails because the `id` exists, respond with `200` and stop.
4. Otherwise, do the work, or enqueue it, in the same transaction as the insert, then respond with `2XX`.

Keep the insert and the work in one transaction. If the work fails, the insert rolls back, your endpoint answers with an error, and the retry gets a clean second chance.

Store the IDs in your database, not in process memory. A retry can reach another server, or the same server after a restart.

## Handle Events Out of Order

Don't rely on arrival order. A `recipient.completed` event can arrive after `envelope.completed` for the same envelope. Two ways to stay correct:

- **Read the current state.** Treat the event as a signal, then fetch the envelope with `GET /v1/envelopes/{envelope_id}` and act on its `status`. The response is always current, whatever order the events came in.
- **Only move forward.** An envelope moves from `processing` to `in_progress` to a final status (`completed`, `canceled` or `failed`) and never back. Ignore an event that would move your record backwards. See the [envelope lifecycle](https://signatureapi.com/docs/api/resources/envelopes/lifecycle).

The event's `timestamp` says when the event happened, not when it was delivered, so you can also use it to order events for one envelope.

## Respond Fast

Answer within a few seconds. Do the slow parts, such as downloading the signed PDF or calling other services, in a background job after you store the event. A slow handler times out, the delivery counts as failed, and the retry adds to the duplicates you have to absorb.

## Recover Missed Events

Retries stop after a while (see [Webhooks > Retries](https://signatureapi.com/docs/api/webhooks#retries)). If your endpoint was down longer, fetch what you missed from the API:

- `GET /v1/events` lists the most recent events in your account, newest first, and filters by `type`. See [List events](https://signatureapi.com/docs/api/resources/events/all).
- `GET /v1/envelopes/{envelope_id}/events` lists the events of one envelope.

Run each listed event through the same handler. Your deduplication table skips the ones you already processed.
