TL;DR: BoldSign has two webhook levels. An app-level webhook sends events only for documents sent through one OAuth app, which suits multi-tenant apps. An account-level webhook covers documents you send from the web app or our eSignature API, which suits a single team.
You have connected your app to BoldSign, and documents go out for signature. Now your app needs to know when someone signs, declines or lets a document expire. Checking each document by hand, or asking the API every few minutes, is slow and wasteful.
Webhooks solve this by sending each event to your app as it happens. Before you turn them on, you choose a level. This guide explains both levels, when to use each, and how to set them up.
How do BoldSign webhooks work?
A webhook is a message we send to a URL on your server whenever an event you chose takes place. Your code reads the message and acts on it.
Think of a doorbell. You could walk to the door every few minutes to check for visitors, or you could wait for the bell to ring. Webhooks are the bell, and checking the API on a timer is the walk to the door.
Events cover the whole signing journey, such as sent, viewed, signed, completed, declined and expired. Our list of available webhook events has the full set. For field names and sample messages, see our sample event data.
Our guide on why webhooks matter in API integration covers the wider picture.
What is the difference between app-level and account-level webhooks?
The two levels send the same kinds of events. They differ in which documents trigger an event and where the events go.
| Point | App-level webhook | Account-level webhook |
|---|---|---|
| Tied to | One OAuth app | No app |
| Documents covered | Sent through that OAuth app | Sent from the web app or the API |
| Endpoint | One URL per OAuth app | One URL for the account |
| Data kept apart | By app, client or environment | One shared stream |
| Fits | Multi-tenant apps, client integrations | One team, internal systems |
Our setup guide lists the steps for an app-level webhook and an account-level webhook.
When should you use app-level webhooks?
Use app-level webhooks when you need to keep events apart by customer, client or environment. Each OAuth app gets its own webhook and URL.
App-level webhooks fit these cases:
- You run a multi-tenant software as a service (SaaS) app and keep each customer’s data apart.
- You want separate webhooks for staging and production.
- You send each client’s events to a different backend system.
- You want to pause one integration without touching the others.
What does an app-level setup look like?
A SaaS platform serves many customers, and each customer has its own BoldSign OAuth app. The platform adds an app-level webhook for each app, pointing at that customer’s pipeline.
When a document is signed, we send the event only to the webhook for that customer’s app. Each customer’s backend receives its own events and nothing else.
When should you use account-level webhooks?
Use an account-level webhook when one team or one internal system needs its document events in one place. You set up a single URL and skip the OAuth app.
An account-level webhook fits these cases:
- A single department, such as human resources (HR), sends documents from BoldSign.
- You want one place to receive and process events.
- You are building an internal dashboard or a monitoring tool.
By default, a webhook sends events you trigger yourself. An administrator can tick Listen to Team user’s events to add the team’s events, as our page on webhook configuration and lifecycle explains. Account admins then receive events from the whole organization.
What does an account-level setup look like?
An HR team sends offer letters and onboarding forms from BoldSign. The team adds one account-level webhook that feeds its HR system.
The HR system listens for completed, declined and expired events. It updates each candidate’s status as soon as the event arrives.
Can you use both webhook levels at once?
Yes. Many teams start with one account-level webhook and add app-level webhooks later, as they take on customers that need their own stream.
Use these rules to pick a starting point:
- Choose app-level when you serve many clients or tenants.
- Choose app-level when staging and production must stay apart.
- Choose account-level when one team or one internal system needs the events.
- Run both when internal reports and customer integrations share one account.
You can move an integration from one level to the other later. Your handler code stays much the same, because the event format matches.
How do you set up each webhook level in BoldSign?
Both levels start on the Webhooks page under API in the BoldSign web app. An app-level webhook needs an OAuth app first, which you create under API, then OAuth Apps.
- Go to API, then Webhooks, and select Add Webhook.
- Select App Level and pick your OAuth app, or select Account Level.
- Enter a name and a public URL that starts with https.
- Choose the events that should trigger a callback.
- Select Verify, then Save once the check passes.
When you select Verify, we send a test event with the eventType set to Verification. Your endpoint must reply with a 200 status code within 10 seconds.
What should contract software with reliable webhooks offer?
Reliable webhooks need work on both sides. We sign and retry each event, and your handler checks, stores and processes it safely.
How do you check that an event came from us?
Each request carries an X-BoldSign-Signature header. Check it with your webhook secret using a hash-based message authentication code (HMAC) with Secure Hash Algorithm (SHA) 256, and reject any request that fails.
For one more layer, accept requests only from our Internet Protocol (IP) addresses. Our guide to webhook IP whitelisting shows how.
How do you handle retries and repeats?
Reply with a 200 status code within 10 seconds, and move heavy work to a background job. We retry a failed delivery up to six times, starting 1 minute later and ending 24 hours later.
A retry can deliver the same event twice, so record each event ID and skip ones you have seen. Our guide to webhook retries and idempotency walks through the patterns.
How do you keep webhooks easy to debug?
Good logs make problems quick to trace. Keep each environment’s secrets, URLs and logs apart.
- Log each event’s ID, type and time of arrival.
- Log failed signature checks and processing errors in detail.
- Never send staging events into production systems.
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, billed yearly. 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 set up and test both webhook levels before you go live.
How do you start with BoldSign webhooks?
The quickest way to choose a level is to try both on a test endpoint. Pick the step that fits you.
- Create a free API sandbox account and add a webhook of each level.
- Read the full BoldSign webhooks documentation for events, payloads and security.
- Ask our support portal for help designing your webhook setup.
Frequently asked questions
What is the main difference between app-level and account-level webhooks?
An app-level webhook sends events only for documents sent through one OAuth app. An account-level webhook is not tied to an app and covers documents you send from the web app or the API.
When should I use app-level webhooks?
Pick app-level webhooks when each customer, client or environment has its own OAuth app. Each app then sends its events to its own URL, so one tenant never sees another's data.
When should I use account-level webhooks?
Pick an account-level webhook when one team or one internal system needs every document event in one place. You set up one URL and skip the OAuth app.
Can I use both webhook levels at the same time?
Yes. Many setups use an account-level webhook for internal reports and app-level webhooks for customer integrations that need their own stream.
Can an account-level webhook receive my team's events?
Yes, when an administrator ticks the Listen to Team user's events box on the webhook. Team admins then get their team's events, and account admins get events from the whole organization.
Do the two webhook levels send different payloads?
The event format is the same. The difference is which documents trigger events, and app-level samples also carry the OAuth app's clientId field.
How does BoldSign handle failed webhook deliveries?
We retry up to six times, from 1 minute to 24 hours apart, when your endpoint fails to reply with a 200 status code within 10 seconds. Build your handler so a repeated event causes no harm.
What should contract software with reliable webhooks offer?
Look for signed requests you can check, a clear retry schedule, a test step before you save, and a choice of which events to receive. We offer all four.