BoldSign Webhooks: App vs Account—How to Choose

Source: Dev.to

Short answer

What you’ll get from this guide

• A quick explanation of how BoldSign webhooks work.
• A clear comparison of App‑Level vs. Account‑Level webhooks.
• Guidance 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 a full list, see the Available Webhook Events – API Documentation.

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

Why use webhooks?

• 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 Sample Event Data.

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

App‑Level vs. Account‑Level Webhooks: Key Differences

App‑Level Webhooks

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:

• Build a multi‑tenant SaaS solution and want isolation per customer.
• Need separate webhooks for staging vs. production.
• Require client‑specific routing to different CRMs, ERPs, or backends.
• Want the option to turn off or adjust one integration without affecting others.

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

App‑Level example scenario

1. A SaaS platform integrates BoldSign for hundreds of customers.
2. Each customer (tenant) has its own BoldSign OAuth app.
3. For each OAuth app, the SaaS defines an App‑Level webhook endpoint that points into that tenant’s integration pipeline.
4. When a document is signed, BoldSign sends the event only to the webhook associated with that tenant’s app.
5. 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

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 internal system that needs to monitor all activity.
• Simplicity is a priority and you prefer a single integration point.
• You don’t require per‑client isolation (e.g., a single organization using BoldSign).

When to Choose Account‑Level Webhooks

The team or department using BoldSign—whether HR, Legal, Finance, Sales, or any other group—might prefer a single place to receive and process all events.

• 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?

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

HR and Employee Onboarding

• Scenario: HR sends offer letters, NDAs, and employment contracts using BoldSign.
• Webhook Level: Account‑Level
• Implementation: A single webhook endpoint feeds the HR system with all document events (sent, viewed, signed, 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 its data, simplifying data segregation and scaling 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 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

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 back‑off.
• Retries typically start at ~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 (CloudWatch, ELK, Datadog, etc.) 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

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, refer to the BoldSign developer documentation.

Additional resources

• For more details, check the official BoldSign Webhooks documentation.
• You can experiment safely with a 30‑day free trial.
• Need help designing the right approach for your integration? Reach out via the BoldSign support portal.

Related blogs

• Simplify Signing Policies and Procedures in Accounting Firms with BoldSign
• How BoldSign Helps with Account Openings in Banking
• File Uploads in the BoldSign Mobile App: Everything You Need to Know

Note: This blog was originally published at boldsign.com.