TL;DR: Webhooks can arrive twice, late or out of order, and that is normal. Your handler should check the signature, reply fast, skip events it has already seen and update records from their current state. Our webhooks documentation explains how BoldSign sends each event to your software as a service (SaaS) app.
A signer finishes a contract. Your app gets the Completed event, saves the PDF and emails the sales team. Ten minutes later the same event lands again, and the team gets a second email.
Nothing is broken on either side. Webhooks retry by design, so your code has to expect repeats. This guide shows how to handle retries, duplicates and out-of-order events in a webhook handler.
Why are webhooks harder than they look?
A webhook looks simple: an event fires and your app reacts. In production, servers restart, deploys happen, traffic spikes and networks drop requests.
Each of those moments can cause a retry or a delay. A handler that expects each event once, on time and in order will break sooner or later.
How do webhooks behave in production?
Most providers use at-least-once delivery. They would rather send an event twice than lose it.
In practice, you should expect the following:
- The same event can arrive more than once.
- An event can arrive minutes or hours late.
- A newer event can arrive before an older one.
A failed integration rarely starts with the provider. It starts with a handler that assumes each event is new and arrives in order.
Why are webhook retries normal and not a bug?
A provider retries when your endpoint is slow, returns an error or cannot be reached. To your app, a retry looks the same as a duplicate.
We follow this model too, as our page on webhook configuration and lifecycle explains. Your endpoint must reply with a 200 status code within 10 seconds, or we count the delivery as failed.
We then retry up to six times, with gaps of 1 minute, 15 minutes, 45 minutes, 1 hour, 8 hours and 24 hours. After the sixth retry, we watch the endpoint for 7 days and email you notices. The webhook turns off if failures go on, and turns back on when your endpoint recovers in that window.
What’s the right way to handle webhook retries in a SaaS app?
Accept that retries will happen and make each step safe to repeat. These five steps cover most SaaS apps.
- Check the signature, and reject any request that fails.
- Save the raw event to a queue or table.
- Reply with a 200 status code well inside the 10-second limit.
- In a background job, skip any event ID you have already handled.
- Apply the change only if it moves the record forward.
Steps 4 and 5 do most of the work. The next sections explain each one.
What does idempotency mean for webhooks?
Idempotency means that handling the same event twice leaves the same result as handling it once. A repeat changes nothing.
An elevator button works the same way. Pressing it five times still calls one elevator.
An idempotent handler spots events it has already seen. It skips repeated side effects, such as emails or charges, and keeps your data consistent.
How do you make a webhook handler idempotent?
Store each event’s ID when you handle it, and skip any ID you have already stored. Every BoldSign event carries an id field in its event metadata for this purpose.
A unique index on the ID column in your database helps. Two workers that receive the same event at once cannot both insert it, so only the first one runs.
Together, these give you once-only results on top of at-least-once delivery. A provider without event IDs makes this harder, so read its docs first.
Why can’t you trust webhook event order?
Events can arrive in a different order from the one they happened in. Retries overlap with new events, network paths differ and workers run side by side.
In a signing workflow, a Completed event can reach you before a Viewed event for the same document. Our list of available events shows every document event, from Sent to Completed.
Arrival order is a weak guide to the truth. Your app needs another way to decide whether to apply an event.
How does state-based processing fix out-of-order events?
State-based processing checks the record’s current state before it applies an event. Your handler then skips any event that would move the record backward.
For each event, your handler should do three things:
- Load the current state of the document or record.
- Check that the event is a valid next step from that state.
- Apply the change, or skip the event if it is stale.
A document that has reached Completed should stay there. A late Viewed event for it changes nothing. Each event also carries a created timestamp that helps you spot stale updates.
How do you verify a BoldSign webhook signature?
Check the signature on every request before your code acts on it. Your endpoint is public, so anyone could send it a fake event.
We sign each request with a hash-based message authentication code (HMAC) using Secure Hash Algorithm (SHA) 256. The X-BoldSign-Signature header holds a timestamp t and a signature s0.
Our guide to verify webhook events shows the full method. In short:
- Copy the signing secret from your webhook settings with the Reveal button.
- Build the signed text from the timestamp, a period and the raw request body.
- Compare your result with
s0using a constant-time comparison. - Reject requests with a timestamp older than your tolerance, such as 5 minutes.
Ignore any request that fails these checks. Signature checks work alongside idempotency, so only trusted events reach your business logic.
What changes in a multi-tenant SaaS app?
In a multi-tenant app, one handler serves many customers. A single mistake can then reach several of them at once.
To keep tenants apart, your handler should:
- Identify the tenant for every event.
- Keep each tenant’s data separate.
- Scope event ID checks to the tenant.
- Keep an audit trail for each tenant.
At this scale, correct webhook handling is a security matter as well as a reliability one.
What mistakes break webhook handling in production?
Most webhook bugs come from a few habits. Watch for these in code review:
- Running business logic before the event ID check.
- Doing heavy work before you reply to the request.
- Trusting the order in which events arrive.
- Letting a record’s state move backward.
- Mixing tenant data in shared code.
In eSignature work, these bugs can store a signed file twice or update a compliance record twice. Customers notice those errors quickly.
Where does reliable webhook handling matter most?
Reliable handling matters most where an event triggers an action you cannot undo. The table shows common cases.
| Situation | What can go wrong | Why handling matters |
|---|---|---|
| Document completion | It runs more than once | Completion should happen once |
| Notifications | Users get repeat messages | Repeats confuse signers and teams |
| Billing or account access | A charge repeats | A double charge costs money and trust |
| Busy systems | Parallel updates collide | State stays correct under load |
| Recovery and replay | Actions run again | Replays become safe |
Which BoldSign plan do you need for webhooks?
Live webhooks and API calls need the Enterprise API plan, from $30 a month with 40 envelopes. Each extra envelope costs $0.75, as listed on the BoldSign pricing page in November 2026.
Prices are in USD.
The free sandbox lets you test webhooks before you go live. Each event’s environment field tells you whether it came from the sandbox or from live use.
How do you start building a reliable webhook handler?
A good way to learn is to send test events to your own endpoint and watch the retries. Pick the step that fits you.
- Create a free API sandbox account and point a test webhook at your handler.
- Read our guide to app-level and account-level webhooks to choose the right type.
- Ask our support portal for help designing your webhook setup.
Frequently asked questions
Why do webhook providers send the same event more than once?
Most providers use at-least-once delivery. They send an event again when they cannot tell whether your endpoint got it, since a repeat is safer than a lost event.
Do webhook events always arrive in order?
No. Retries, parallel workers and network delays can all reorder events, so your code should decide from the record's current state, not from arrival order.
What happens if a webhook handler is not idempotent?
Each repeat runs as a new event. You can end up with double emails, repeated status changes or a charge that runs twice.
Should I process a webhook inside the request?
Usually not. Check the signature, save the event, reply with a 200 status code and do the heavy work in a background job.
How long does BoldSign wait for a webhook response?
We wait 10 seconds for a 200 status code. A late reply or any other status code counts as a failed delivery, and we retry it.
What happens when a BoldSign webhook endpoint keeps failing?
After six failed retries, we watch the endpoint for 7 days and email you about it. The webhook is turned off if failures go on, and turns back on if the endpoint recovers in that time.
What if I need a webhook platform that enforces idempotent delivery?
Store each event ID in your own database and skip any ID you have already handled. Provider settings help, but your own check is what keeps repeats from reaching your business logic.
Do top webhook platforms with built-in duplicate event detection remove the need for idempotency?
No. A platform can filter some repeats, but your endpoint can still see the same event after a timeout or a replay. Keep your own event ID check either way.