Stay up to date with AI tools, model releases, and developer workflows that matter.

Weekly. Free. One click to leave.

7 Day Free Trial. Cancel Anytime.

Sending a document for signature is the easy part of an e-signature integration. One POST request and the signer gets an email. The work that actually breaks in production happens afterwards: knowing when the document was signed, trusting the notification that told you so, handling the same notification twice, and getting the final PDF into storage before the download link expires.

This tutorial builds that whole loop in Node.js with Express. An event in your app (a deal is approved, a client is onboarded, a task moves to "ready to sign") sends a contract from a template. When the signer finishes, a webhook arrives, your server verifies it, and the signed PDF plus its audit trail get saved without anyone touching them.

The code uses Firma.dev, the e-signature API I work on, because I needed a real API to make the examples runnable. The patterns are not specific to it, though. Signature verification, idempotent handlers, short-lived download URLs, and reconciliation jobs show up in almost every webhook-driven integration, and the same structure applies whether you're receiving events from a payment processor, a CI system, or another signing provider.

According to recent reports, there's a fifth part that tutorials usually skip: a reconciliation job that catches anything the webhooks missed. We'll build that too, because webhooks are a notification mechanism, not a delivery guarantee.

Set three environment variables:.

In a recent development, before sending anything, wrap the HTTP calls in one place. This is where authentication lives, and it's also where you handle 429 Too Many Requests once instead of in every caller. Most APIs, this one included, return a Retry-After header on a 429, so the client should honour it rather than guessing a backoff.

It has been revealed that the 503 branch matters later. When a document has just been completed, the final PDF and its completion certificate take a moment to generate, and the download endpoint states so with a 503 and a Retry-After instead of handing you a half-built file.

In a recent development, the trigger depends on your product. It might be a route handler, a queue consumer, or a CRM automation calling into your service. What matters is that the function doing the sending is small and takes plain data:.

Two design choices are worth calling out.

Sources indicate that use a single create-and-send call when you can. Many signing APIs split this into "create a draft" and "send the draft." That's useful when a human needs to review the document first, but for automation it creates a window where your process can crash between the two calls and leave an orphaned draft. A combined endpoint makes the operation atomic from your side.

According to recent reports, store the provider's ID on your own record immediately. Webhook payloads reference the signing request, not your deal or customer. Without that mapping you'll end up searching by email address, which falls apart as soon as one client signs two documents.

Here's the first place integrations quietly go wrong. Webhook signatures are computed over the exact bytes the sender transmitted. If Express parses the body as JSON first, you lose those bytes, and re-serialising the object won't reproduce them (key order, whitespace, and number formatting can all change). Signature checks then fail intermittently, which is the worst kind of failure.

The fix is to use express.raw() on the webhook route only, so the handler receives a Buffer:.

Recent findings suggest that most webhook providers sign payloads with HMAC-SHA256 using a shared secret. The details vary, so read your provider's docs for the exact header format, but the scheme here is common: the header looks like t=1731456000,v1=5f2b..., and the signed string is the timestamp, a dot, and the raw body. Stripe uses a very similar format, and the Standard Webhooks spec describes the same idea as a vendor-neutral convention.

Each line here defends against something specific.

The OWASP guidance on cryptographic storage covers the other half of this: the secret belongs in an environment variable or secrets manager, never in the repository.

Sources indicate that every serious webhook system delivers at least once, not exactly once. If your endpoint is slow, returns a 5xx, or the network drops the response, the sender retries. Firma.dev, for example, makes up to three attempts per event (immediately, then after at least five minutes, then after at least an hour) and treats anything other than a 2xx as a failure, including redirects. Other providers retry more aggressively. Either way, your handler will eventually see the same event twice.

The defence is to record each event's unique ID and skip ones you've seen. In the server above that's alreadyProcessed and markProcessed. For a demo, a Set works:.

In production, use your database and let a unique constraint do the work, so two concurrent deliveries can't both pass the check:.

Sources indicate that also notice the order in the route: respond with 200, then do the work. Many providers time out deliveries after a few seconds (five, in this case). Downloading a PDF and uploading it to object storage can easily take longer than that, and a timeout counts as a failure, which triggers a retry, which triggers duplicate work. Acknowledging fast and processing asynchronously avoids that loop.

According to recent reports, setImmediate is fine for a tutorial, but it has a real weakness: if the process dies after sending the 200 and before finishing the work, the event is acknowledged and lost. In production, push the event onto a durable queue (BullMQ, SQS, a jobs table) before responding. Step 7 covers the safety net for whatever still slips through.

Now the actual business logic. You'll usually see several event types (sent, viewed, a signer signed, declined, expired, completed). Only one of them means "the document is final":.

Three things in here are easy to get wrong.

Industry observers note that don't treat "a signer signed" as "the document is done." With multiple signers, each one triggers its own event, and a per-signer "all complete" flag can be true on more than one of them. Key your storage logic off the single completion event.

Recent findings suggest that don't persist the download URL. Pre-signed URLs expire (this one carries an expires_at). Saving the link to your database and serving it to customers later produces broken links a few minutes or hours later. Download the bytes and store them in storage you control. Swapping the fs.writeFile calls for an S3 PutObject or a Google Drive upload is a drop-in change.

According to recent reports, store the audit trail, not just the PDF. If a signature is ever disputed, the PDF indicates what was signed, and the audit trail shows who signed it, when, and from where (timestamps, IP addresses, the sequence of views and signatures). That evidence is what makes an electronic signature defensible, which brings us to the legal side.

Retries are finite. Endpoints go down during deploys. Some providers auto-disable a webhook after enough consecutive failures, and events aren't guaranteed to arrive in order. Any one of these can leave a completed document sitting unsaved.

A small scheduled job closes that gap. Keep a list of signing requests your app considers "pending," and periodically ask the API for their real status:.

Since storeSignedDocument overwrites by ID, running it twice for the same document is harmless. That's the property you want from every step in a webhook pipeline: doing it again shouldn't change the result.

None of this is legal advice, but a few facts shape how you build.

Recent findings suggest that in the US, the ESIGN Act and the Uniform Electronic Transactions Act (adopted by 49 states) give electronic signatures the same legal standing as handwritten ones for most commercial documents. ESIGN also has requirements around consumer consent and record retention, which is part of why you store the final PDF yourself rather than relying on a third-party link.

In a recent development, in the EU, eIDAS defines three levels: simple (SES), advanced (AdES), and qualified (QES). SES and AdES cover most business contracts. QES requires a qualified trust service provider and certificate-based identity, and some documents (certain property transfers and court filings, depending on the country) require it or exclude e-signatures entirely. Check which level your document types need before you pick a provider, since not every API offers every level.

Sources indicate that across jurisdictions, the evidence that holds up is the same: who signed, how they were identified, when it happened, and proof the document hasn't changed since. That's the audit trail and the completion certificate, which is why Step 6 stores both.

If you're evaluating providers for a workflow like this, the questions that matter at the integration level are mostly not on the pricing page:.

Recent findings suggest that the send call is one line. The reliability comes from everything around it: keeping the raw body for verification, checking timestamps and comparing in constant time, acknowledging fast and deduplicating by event ID, downloading files before their links expire, and running a reconciliation job for the events that never arrive. Get those right and contract signing becomes something your app does in the background, with no one chasing signatures or copying PDFs between folders.

For the Firma.dev-specific details used here (event names, header format, rate limits), see the webhooks guide.

7 Day Free Trial. Cancel Anytime.

→ Read original article