TL;DR: An API answers when your app asks, and a webhook tells your app the moment something happens. Webhooks save your app from asking for updates again and again. Our eSignature API sends a webhook when a document is sent, viewed, signed or completed.
Your app sends a contract for signature. Now it needs to know when the customer signs, so it can update the deal and file the PDF.
You could ask the server every minute. Or the server could tell you once, right when the signature lands. That second option is a webhook, and this guide shows how it works in the BoldSign eSignature platform.
What is a webhook vs API?
An API is a set of rules that lets one app ask another app for data or actions. A webhook works the other way round: the other app sends you data as soon as an event happens.
Think of a parcel delivery. Using only an API is like walking to the front door every ten minutes to check for the box. A webhook is the text message that says your parcel has arrived.
Most integrations use both. Your app calls the API to send a document, and a webhook reports what happens to it next.
What is a webhook endpoint?
A webhook endpoint is a public web address on your server that receives webhook events. When an event happens, we send a web request with the event data to that address.
Your code at the endpoint reads the event and acts on it. For example, it can mark a deal as signed or start a download of the finished file.
Why do webhooks matter in API integration?
Webhooks remove the need for constant polling. Your app gets each update once, at the moment it happens, instead of asking over and over.
Polling has real costs. Each check is a request your server sends and ours must answer, even when nothing has changed. Frequent checks can also run into API rate limits, which can block requests you need.
Polling code is also harder to maintain. You have to write the timer, the error handling and the retry logic yourself.
Users notice the delay too. A customer who has just signed expects your app to show it right away, not on the next polling cycle.
Many teams choose e-signature APIs with webhook support and direct database sync to eliminate manual re-entry entirely. A webhook supplies the sync part: your handler writes each status change straight to your database, so nobody copies it by hand.
How does BoldSign use webhooks?
We use webhooks to send real-time notifications about your documents. You choose the scope of each webhook when you create it.
What is an app-level webhook?
An app-level webhook fires for documents sent through one OAuth app. It suits developers who want events from a single integration only.
What is an account-level webhook?
An account-level webhook fires for documents sent from the BoldSign web app or the API. It covers all activity across your account.
Our guide to app-level and account-level webhooks compares the two with examples.
Which events can trigger a BoldSign webhook?
Document events cover each step of signing. You can listen to single events or to all of them.
- Sent: a signature request goes out to recipients.
- Viewed: a recipient opens the document.
- Signed: one recipient signs the document.
- Completed: every recipient has signed.
- Declined: a recipient declines the request.
Other document events report a document that was edited, revoked, reassigned or expired. Some report a reminder, a new draft, or a failed email delivery or send.
Outside documents, there are events for signer authentication and identity verification, sender identities and templates. Our sample event data shows what each event looks like.
How do you set up a webhook in BoldSign?
You add a webhook from the API area of the BoldSign web app. Our guide to setting up a webhook shows each screen.
- Go to API, then Webhooks, and select Add Webhook.
- Choose App Level or Account Level, and give the webhook a name.
- Enter a public web address that starts with https.
- Select Verify, so we can send a test event to your endpoint.
- Pick the events you want, then select Save.
For an app-level webhook, create the OAuth app first under API, then OAuth Apps.
What happens when your endpoint does not respond?
Your endpoint must reply with status code 200 within 10 seconds. A late reply or an error counts as a failed delivery, and we retry the event.
| Retry | Sent after |
|---|---|
| 1st | 1 minute |
| 2nd | 15 minutes |
| 3rd | 45 minutes |
| 4th | 1 hour |
| 5th | 8 hours |
| 6th | 24 hours |
We watch the endpoint for 7 days once all six retries fail. The webhook is marked for disabling when the failures go on, and we email you along the way.
The webhook turns itself back on if your endpoint starts replying within that 7-day recovery period. Our webhook lifecycle page has the details.
How do you build a reliable webhook handler?
A handler that stays reliable plans for slow replies, repeat events and fake requests. These habits cover the common cases:
- Reply with status code 200 first, then process the event in the background.
- Store each event ID and skip events you have already processed.
- Check the X-BoldSign-Signature header to verify each webhook event.
- Log every event so you can trace problems later.
- Resend an event from Webhook History to test your endpoint.
Our guide to webhook retries and idempotency explains duplicate and out-of-order events. To put a webhook to work, see how to automatically download signed documents with webhook callbacks.
Which BoldSign API plan includes webhooks, and what does it cost?
Webhooks for live documents need the Enterprise API plan, from $30 a month with 40 envelopes. That is the price listed on the BoldSign pricing page in November 2026, in USD, and each extra envelope costs $0.75.
The plan also includes identity verification for signers. To build and test your handler first, use the free API sandbox.
Where do you go next with webhooks?
Start with one event, such as Completed, and a test endpoint. Add more events once your handler works.
- Create a free API sandbox account and point a webhook at your test endpoint.
- Book a demo to see webhooks set up for your integration.
- Contact our support team with a question about your webhook setup.
Frequently asked questions
Is a webhook the same as an API?
No, though a webhook is often part of an API. You call an API when you want data. A webhook calls you when an event happens.
What should I look for in contract software with webhooks?
Look for clear event types, a signed request you can check, and a retry plan for failed deliveries. A delivery history with manual resend also helps when you debug.
Which features matter in e-signature APIs enabling real-time document creation with API integration and webhook support?
You need endpoints that create and send documents from your app, plus webhooks that report each status change. Our API covers both, and our webhooks report events such as Sent, Viewed, Signed and Completed.
Does BoldSign offer a digital signature API with webhook support?
Yes. The BoldSign eSignature API sends webhook events for documents, templates, sender identities and signer authentication. You choose which events each webhook listens to.
How fast must my endpoint respond to a BoldSign webhook?
Your endpoint must reply with status code 200 within 10 seconds. Reply first and do the slow work afterward, so the request does not time out.
What happens if my webhook endpoint is down?
We retry the event six times, from 1 minute to 24 hours after the first try. After that, we watch the endpoint for 7 days before we disable the webhook.
How do I know a webhook request really came from BoldSign?
Check the X-BoldSign-Signature header on each request. We sign every event with your webhook signing secret key, and you ignore any request whose signature does not match.
Which BoldSign plan includes webhooks?
Webhooks for live documents come with the Enterprise API plan, from $30 a month with 40 envelopes. You can build and test them first in a free API sandbox account.