Vijay Amalan for BoldSign

Posted on Dec 19 • Originally published at boldsign.com

BoldSign Webhooks: App vs Account—How to Choose

#esignature #boldsign #webhook #appvsaccount

If you are integrating the BoldSign API into your application, you need reliable, real-time visibility into what your documents are doing:

Did someone sign the document?
Was it declined?
Is it ready for the next workflow step?

Without reliable updates, teams end up hacking around the problem with manual checks, API polling, or delayed notifications. That means slower workflows and a higher chance of missing critical events.

BoldSign Webhooks fix this by pushing events to your application as they happen. But there’s a key architectural decision you need to make before turning them on:

Should you use App-Level Webhooks or Account-Level Webhooks?

Short answer:

Use App-Level Webhooks when you need tenant or integration isolation for multitenant SaaS, per-client routing, and separate staging and production environments.
Use Account-Level Webhooks when you want one simple webhook endpoint and full account-wide visibility for single teams or internal systems.

This guide is written for developers integrating BoldSign into their systems. You’ll get:

A quick explanation of how BoldSign webhooks work
A clear comparison of App-Level vs Account-Level webhooks
Information on when to choose each option, with realistic scenarios.
A decision framework you can apply to your architecture
Technical best practices for reliable, secure webhook handling

How BoldSign Webhooks Work

This section explains what BoldSign webhooks are at a high level and why they matter for keeping your integration in sync.

BoldSign webhooks are HTTP POST requests that BoldSign sends to your endpoint whenever subscribed events occur.

These events cover the full signature lifecycle, including:

Document events: Sent, viewed, signed, completed, declined, expired
Authentication events: Authentication failed, Identity Verification Initiated

For more details, see the Available Webhook Events – API Documentation 

Instead of polling the BoldSign API, BoldSign calls your webhook endpoint whenever something important changes.

Webhooks let you:

React instantly to critical changes
Eliminate or minimize API polling
Automate workflows and backend updates
Maintain accurate, real-time document tracking

For the full payload schema and sample JSON, refer to our documentation on sample event data. That’s where you’ll see exactly which fields are included and how events are structured.

To configure your first webhook, see our guide on Setting Up a Webhook guide.

App-Level vs Account-Level Webhooks: Key Differences

Here, we’ll zoom out and compare App-Level and Account-Level webhooks side by side so you can see how their behaviors differs.

BoldSign supports two webhook “levels”:

App-Level Webhooks
Account-Level Webhooks

They send the same kinds of events, but they differ in scope, routing, and how you structure your integration.

Below is a compact comparison you can use when designing your architecture.


Aspect	App-Level Webhooks	Account-Level Webhooks
Scope	Events from one specific OAuth application	Events across the entire BoldSign account
Best for	Multi-tenant SaaS apps, client-specific integrations, staging vs production separation	Single-team workflows, centralized tracking, simple integrations
Key benefit	Strong isolation and routing flexibility	Complete visibility with one webhook endpoint
Webhook endpoint	A unique URL per OAuth app	One URL for all events
Data Separation	Cleanly separated by app or client	Unified stream of all account activity
Scalability	Add apps without affecting others	Easiest to maintain; only one webhook configuration
Visibility	Limited to that app’s documents	Full account-wide visibility

App-Level Webhooks

This section focuses on App-Level webhooks: what they are, when they make sense, and how they behave in real applications.

What they are

App-Level Webhooks send events only for the documents created or sent through a specific OAuth application in BoldSign.

If you have multiple OAuth apps, per client or per environment, each app can have its own webhook configuration and URL.

When App-Level Webhooks make sense

Choose App-Level Webhooks if:

You are building a multi-tenant SaaS solution and want isolation per customer
You want separate webhooks for staging vs production
You need client-specific routing to different CRMs, ERPs, or backends
You want the option to turn off or adjust one integration without affecting others

In short: App-Level are the right choice when you care heavily about isolation and routing control.

App-Level example scenario

A SaaS platform integrates BoldSign for hundreds of customers.
Each customer (tenant) has its own BoldSign OAuth app.
For each OAuth app, the SaaS defines an App-Level webhook endpoint that points into that tenant’s integration pipeline.
When a document is signed, BoldSign sends the event only to the webhook associated with that tenant’s app.
The tenant’s CRM or backend receives only its own document events.

Result: Clean separation per client, clear routing, and a scalable pattern for multi-tenant systems.

Account-Level Webhooks

This section explains Account-Level webhooks: how they work, who they’re for, and why they’re often the simplest starting point.

What they are

Account-Level Webhooks apply to your entire BoldSign account. You configure one webhook endpoint, and BoldSign sends all document events for that account to that URL.

Everything happening in that account’s documents flows into one central webhook.

When Account-Level Webhooks make sense

Choose Account-Level Webhooks if:

You have a single team or department using BoldSign, whether that’s HR, Legal, Finance, Sales, or otherwise.
You want one place to receive and process all events
You are building internal dashboards or centralized monitoring
You want the simplest possible configuration with minimal moving parts

In short: Account-Level is ideal when simplicity and full visibility matter more than strict per-tenant separation.

Account-Level example scenario

An HR team uses BoldSign to send offer letters, NDAs, and onboarding documents.
They configure a single Account-Level webhook that sends all events into their HR system.
The HR system listens for “completed”, “declined”, and “expired” events and updates candidate status in real time.

Result: One integration, one webhook, and complete visibility over all HR document activity.

Decision Guide: Which Webhook Level Should You Choose?

This section gives you a quick decision framework so you can map your architecture to the right webhook level without overthinking it.

Use the following rules of thumb:


Scenario	Recommended Webhook Level
You support multiple clients or tenants	App-Level
You use separate staging and production environments	App-Level
You need strict data isolation between clients or integrations	App-Level
You have one team or one internal integration	Account-Level
You want simplicity and full account-wide visibility	Account-Level
You are building an internal dashboard for all document activity	Account-Level

In many real-world setups, teams start with Account-Level for simplicity. As they grow into multi-tenant or more complex integration patterns, they introduce App-Level for use cases that require isolation.

You are not locked into a single pattern forever. You can:

Start with Account-Level for your first integration
Introduce App-Level webhooks per tenant or product later
Run both types side by side if your architecture needs it

How This Choice Plays Out in Real Workflows

Now that you know when each webhook level fits, it helps to see how the decision shows up in actual day-to-day workflows.

HR and Employee Onboarding
- Scenario: HR sends offer letters, NDAs, and employment contracts using BoldSign.
- Webhook Level: Account-Level
- A single webhook endpoint feeds the HR system with all document events, whether documents are sent, viewed, signed, or declined.
- Impact: Automates status updates in HR dashboards, triggers onboarding workflows, and ensures no candidate slips through the cracks.
Sales Contract Management for Multi-Tenant SaaS
- Scenario: A SaaS vendor manages contracts for many separate customers.
- Webhook Level: App-Level
- Why: Each customer has its own OAuth app, so each tenant’s events go to its own webhook endpoint.
- Impact: Each customer’s CRM or backend receives only their data, which simplifies data segregation and scales across hundreds of accounts.
Legal Compliance and Audit Trails
- Scenario: A law firm needs a reliable, detailed audit trail for every signing event.
- Webhook Level: Either App-Level or Account-Level, depending on integration design.
- Why: Webhooks deliver completed, declined, or signed events in real time, which can be logged into compliance systems.
- Impact: Automatically builds a verifiable audit trail, reducing manual effort and risk during audits.
Internal Operations Dashboard
- Scenario: A company wants a central dashboard to see all documents across teams.
- Webhook Level: Account-Level
- Why: One webhook that streams all document events into a data warehouse or analytics service.
- Impact: Cross-team visibility and reporting with minimal configuration.

Technical Best Practices for BoldSign Webhooks

This section covers the operational details that keep your webhook integration secure, reliable, and easy to debug.

Signature verification

Each webhook request includes an X-BoldSign-Signature header.
Verify this signature using HMAC-SHA256 and your webhook secret.
Reject requests where the signature check fails.

Fast, predictable responses

Respond with HTTP 200 within 10 seconds for successful processing.
If processing is heavy, enqueue work to a background job and return 200 quickly.

Retry handling

BoldSign retries failed deliveries with exponential backoff.
Retries typically start at around 1 minute and continue up to 24 hours.
Design your handler to be idempotent so that retried events do not corrupt data or create duplicates.

Robust logging

Log incoming event IDs, types, and timestamps.
Log verification failures and processing errors with enough detail to debug.
Aggregate logs in your usual stack, whether that’s CloudWatch, ELK, Datadog, or another option so issues are easy to trace.

Separation by environment

If you use App-Level for staging vs production, clearly separate secrets, URLs, and logs.
Never send staging webhooks into production systems or vice versa.

Conclusion

This section wraps up the key ideas so you can make a clear decision and move on to implementation.

Choosing the right webhook level in BoldSign is less about syntax and more about architecture:

Choose App-Level Webhooks if you need precision, tenant isolation, or environment separation. They are ideal when you support multiple clients, maintain separate environments, or want fine-grained routing per OAuth app.
Choose Account-Level Webhooks if you want simplicity, centralized visibility, and just one webhook endpoint to manage. They are ideal for single teams, internal dashboards, and straightforward integrations.

Both approaches give you real-time, event-driven workflows without polling. The right choice depends on how your systems, teams, and integrations are structured.

To go deeper into configuration, payload formats, event types, and security details, check the official BoldSign Webhooks documentation. You can experiment safely with a 30-day free trial or reach out via the BoldSign support portal if you want help designing the right approach for your integration.

Related blogs

Note: This blog was originally published at boldsign.com

DEV Community