eSign Webhooks: A Developer Guide to Document Status Events

An e-signature webhook is an HTTPS request that the signing platform sends to your server when something happens to a document: it is viewed, signed, declined or completed. Instead of calling the API every few minutes to ask “is it done yet?”, you receive a push the moment the status changes. This guide shows you how to build a listener that is secure, fast and safe to run in production, and what to check in any provider’s webhook documentation before you commit to it.

TL;DR

• Use webhooks for document status changes and keep polling only as a reconciliation fallback.
• Verify every request with a signed secret and a timestamp check before you touch the payload.
• Return a 200 OK fast: validate, queue the event, and do the real work asynchronously.
• Deduplicate on the event ID, expect out-of-order delivery, and re-fetch the document from the API as the source of truth.
• Treat the signed document and its audit trail as legal records: log what you received and when.

Table of Contents

• What e-signature webhooks do for you
• The document events worth subscribing to
• Build the endpoint step by step
• Handle retries, duplicates and ordering
• Scope your subscriptions carefully
• Test before you go live
• Why the legal record matters
• Our perspective: webhooks belong inside the workflow
• How to evaluate a provider’s webhook support
• Run signing workflows with BeeSign
• Common mistakes to avoid
• FAQ
• Sources

What e-signature webhooks do for you

A signing workflow has several moments your own system cares about. A recipient opens a contract. A signer completes their part. The last signer finishes and the document is final. Someone declines. Each of these should trigger something in your product: unlock an account, start an onboarding checklist, release a payment, file a PDF in storage, or notify a sales rep.

There are two ways to learn about those moments.

For anything customer-facing, such as a tenant waiting for a lease to be confirmed or a new hire waiting for access, the delay from polling is visible. Webhooks remove it. They also scale better: you do work only when something changes.

The document events worth subscribing to

Providers name events differently, so read your provider’s reference. Most cover the same lifecycle:

• Sent or created: the document was sent for signature.
• Viewed or opened: a recipient opened it. Useful for follow-up reminders.
• Signed (per signer): one participant finished. Important for multi-party agreements and signing order.
• Completed: every required signer is done and the final document exists.
• Declined or voided: the process ended without a valid signature.
• Expired: the deadline passed.

Start with the smallest set that drives a real action. In most integrations that means completed and declined, plus signed if you run multi-signer flows. Add viewed only if you will actually use it. Every extra event is more traffic to secure, store and debug.

Build the endpoint step by step

1. Create a dedicated HTTPS route

Use a route that does one job, for example POST /webhooks/esign. It must be reachable over HTTPS with a valid certificate. Keep it separate from your user-facing API so you can apply its own rate limits, logging and access rules.

2. Read the raw body

Signature checks run over the exact bytes the sender transmitted. If your framework parses the JSON and you re-serialize it, whitespace and key order can change and the signature will fail. Capture the raw request body first, verify, then parse.

3. Verify the signature

Without verification, your URL is an unauthenticated door into your processing logic. Anyone who finds it can post a fake “completed” event. The Standard Webhooks specification describes a common pattern: the sender signs a string made from the message ID, a timestamp and the body, joined by full stops, and sends the ID, timestamp and signature as headers. Your server recomputes the signature with the shared secret and compares.

A minimal flow looks like this:

1. Read the ID, timestamp and signature headers.
2. Build the signed content from the ID, timestamp and raw body.
3. Compute an HMAC with your webhook secret.
4. Compare using a constant-time function, never a plain string comparison.
5. Reject the request with 401 if anything does not match.

Treat the webhook secret like a password. Store it in a secrets manager or environment variable, never in source control, and rotate it if it might have leaked. The format of the headers differs by provider, so follow your provider’s documentation rather than assuming it matches the specification.

4. Check the timestamp

A valid signature on an old request is still a replay. Reject requests whose timestamp falls outside a short window. A tight window, a few minutes, limits what an attacker can do with a captured request. We cover this idea in more depth in our post on e-signature API security and replay windows.

5. Queue the event and respond

Your endpoint should validate the request, write the payload to a durable queue or database table, and return 200 OK immediately. Do not generate PDFs, call third-party services or update ten tables inside the request. Providers expect a 2xx response within a limited time, commonly somewhere between a few seconds and about half a minute depending on the platform, and treat anything slower as a failure and retry. A queue protects you from that, and from your own downstream outages.

POST /webhooks/esign
1. Read raw body and headers
2. Verify signature and timestamp  -> 401 if invalid
3. Insert event into queue (store event ID)
4. Return 200 OK

A worker then picks events off the queue at its own pace.

6. Fetch the current state

Do not treat the payload as the source of truth. Use the notification as a trigger, then call the API with your Bearer token to read the document’s current status and, if it is complete, download the final file. This protects you from stale or partial data in the body and from events that arrive out of order.

Handle retries, duplicates and ordering

Webhook delivery is “at least once”, not “exactly once”. Plan for three things.

Retries. If your endpoint times out or returns a non-2xx status, the sender tries again, usually with growing intervals over a period that can last a day or more depending on the provider. This is why a slow endpoint is dangerous: one failing listener can produce a stream of repeats.

Duplicates. Store each event’s unique ID in a table with a unique constraint. When an event arrives, insert the ID first. If the insert fails, you have already seen it, so return 200 and skip the work. Use the event ID, not only the document ID, because one document produces many legitimate events.

Ordering. Do not assume a signed event arrives before completed. Design handlers as state transitions that are safe in any order. For example, ignore an event that would move a record backwards, and let the API fetch in step 6 settle what the real state is.

Here is a small idempotent handler sketch:

onEvent(event):
  if events.exists(event.id): return
  events.insert(event.id)
  doc = api.get("/documents/" + event.documentId)
  if doc.status == "completed":
    storeFinalPdf(doc)
    markContractActive(doc.externalRef)

The endpoint paths above are placeholders. Use the ones in your provider’s reference.

Scope your subscriptions carefully

Most platforms let you register webhooks at different levels: for the whole account, or for a single resource such as one agreement. Account-wide listeners are convenient, but a failing endpoint then affects everything. Where your provider offers resource-level subscriptions, they isolate failures: one broken subscription cannot hold up notifications for unrelated documents. If you must use one account-level endpoint, keep it fast and queue-backed so it never becomes the bottleneck.

Also keep separate endpoints and secrets for test and production. Sending sandbox events into a production listener is a classic way to mark a real contract complete by mistake.

Test before you go live

1. Expose a local server. Use a tunneling tool to give your development machine a temporary HTTPS URL, and register that as the endpoint.
2. Send a test envelope. Run a real signing flow in a trial or sandbox account and watch each event arrive.
3. Break it on purpose. Return a 500 once and confirm that the retry arrives and is deduplicated. Send a request with a bad signature and confirm it is rejected. Replay an old request and confirm the timestamp check catches it.
4. Simulate out-of-order delivery. Feed completed before signed into your handler.
5. Monitor in production. Alert on rising 401 counts, queue depth and the age of the oldest unprocessed event.

Keep a reconciliation job as a safety net. Once a day, list documents that your database shows as pending for longer than expected and check their status through the API. It costs little and catches events lost to extended outages.

Why the legal record matters

A webhook is a notification, not the contract. Under the federal E-SIGN Act of 2000, electronic signatures, contracts and records carry the same legal equivalence as paper ones in commerce, and the Act does not prescribe a particular technology. So what you must preserve is the signed document and its audit trail from the platform, not your own copy of a JSON payload. Still, log the event ID, timestamp and the status you fetched for each transition. If a dispute arises, a clean chain of “event received, state verified, file stored” helps your team explain what happened. If you handle HR files, this Portuguese-language overview of when electronic signatures hold in HR records shows how another jurisdiction approaches the same question. For U.S. rules, see our guide to e-signature compliance laws for U.S. businesses and our explanation of what makes an e-signature valid. For anything specific to a contract type or state, ask your attorney.

Our perspective: webhooks belong inside the workflow

We build BeeSign as a workflow-native e-signature platform, and that shapes how we think about webhooks. A signature is rarely the end of a process. It is the step that unlocks the next one: an approval, an identity check, a stored record, a welcome email. Webhooks are the seam where signing meets the rest of your product, so we believe three things.

First, the seam should be boring. A listener that validates, queues and acknowledges is easy to reason about, and the complexity lives in workers you can retry and test.

Second, you should not pay per event for building on it. BeeSign uses predictable, flat-rate pricing without per-envelope fees, so more automation does not mean a bigger bill.

Third, many teams do not want to own every integration. We build and maintain integrations for clients, so your developers can spend time on your product instead of API plumbing. For organizations with strict data rules, our white-label option and bring-your-own-cloud storage keep documents within your own infrastructure, with your branding and your domain.

Whichever platform you choose, hold it to the same standard: signed requests, documented retries, a way to fetch current state, and a full audit trail.

— Mustafa Abusharkh

How to evaluate a provider’s webhook support

If you are choosing an e-signature API, use this checklist while reading the docs.

A provider that answers these clearly will save you weeks of debugging. One that hides the retry policy or lacks event IDs will cost you later.

Run signing workflows with BeeSign

If you want e-signatures, reusable templates, identity verification and a REST API in one platform, start with the BeeSign electronic signature product. You can add identity verification with government ID capture and biometric face matching, or look at white-label and bring-your-own-cloud if documents must stay in your infrastructure. Plans start with the Individual plan at 9.99 USD per month, and every plan begins with a 7-day free trial. See the pricing page for Enterprise and customized integrations.

Common mistakes to avoid

• Skipping verification in development and forgetting it later. Make verification part of the first version, not a ticket for next quarter.
• Doing heavy work in the request. It leads to timeouts, which lead to retries, which lead to duplicates.
• Trusting the payload. Fetch the document and decide from the API response.
• Deduplicating on document ID. Use the event ID.
• Logging secrets or full payloads with personal data. Contracts carry names, addresses and sometimes ID details. Redact logs and limit retention.
• No monitoring. A silent listener failure looks like “nobody is signing” until a customer calls.

FAQ

What is the difference between a webhook and an API call?

With an API call, your server asks the platform for data. With a webhook, the platform sends data to your server when an event occurs. Most integrations use both: the webhook announces a change and an API call fetches the current document state.

How fast must my endpoint respond?

Providers differ, and the window is commonly somewhere between a few seconds and about 30 seconds. Check your provider’s documentation. The safe pattern is to verify, queue and return 200 OK right away, so processing time never matters.

What happens if my server is down when an event is sent?

Most platforms retry for a period of hours or days, but the schedule varies. Build for it by making handlers idempotent, and run a daily reconciliation job that compares pending documents against the API so nothing is lost after a long outage.

Do I still need to poll the API?

Not for normal status tracking. A low-frequency reconciliation check is still good practice, because no delivery system is perfect. It is a safety net, not the main mechanism.

Are webhook notifications legally binding?

No. The notification is only a signal. The legal record is the signed document and its audit trail, which the E-SIGN Act treats as equivalent to paper. Keep those safely stored, and talk to your attorney about specific document types.

Sources

• Standard Webhooks specification
• E-SIGN Act guidance, Public Law 106-229

Recommended

• 5 Minute Replay Window: E-signature API Security for Developers
• How to Track Document Signature Status