Skip to content

Best practices

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.

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

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