Understanding Webhooks

What Are Webhooks?

A webhook is an HTTP-based callback mechanism that allows PandaDoc to notify your application immediately when specific events occur, such as document status changes or template updates. Instead of your application repeatedly asking PandaDoc "Has anything changed?" (polling), webhooks let PandaDoc tell your application "Something changed!" the moment it happens.

Real-World Analogy

Think of webhooks like a doorbell system:

• Polling is like repeatedly checking your door to see if anyone's there
• Webhooks are like having a doorbell that rings when someone arrives

How Webhooks Work

The Webhook Flow

1. Setup: You register a webhook subscription with PandaDoc, specifying:

   • Your endpoint URL (where to send notifications)
   • Which events you want to be notified about
   • What additional data to include

2. Event Occurs: Something happens in PandaDoc (e.g., a document is signed)

3. Notification: PandaDoc immediately sends an HTTP POST request to your endpoint with event details

4. Processing: Your application receives the notification and takes appropriate action

5. Acknowledgment: Your application responds with HTTP 200 to confirm receipt

Workspace Isolation

Webhooks operate at the workspace level, meaning:

• Each webhook subscription only receives events from its specific workspace
• Multi-workspace integrations require separate subscriptions for each workspace
• Consider using workspace identifiers in your webhook URLs for easier routing

Why Choose Webhooks Over Polling?

Webhooks vs. Polling Comparison

Benefits of Webhooks

Efficiency

• Immediate notifications: No delay between event and notification
• Reduced API calls: No need to continuously poll for changes
• Lower bandwidth: Only receive data when something actually changes

Scalability

• Better resource utilization: Your servers aren't constantly making unnecessary requests
• Reduced rate limiting: Fewer API calls mean less risk of hitting rate limits

User Experience

• Real-time responsiveness: Users see updates immediately
• Reduced latency: No waiting for the next polling cycle
• Better reliability: Less chance of missing events due to polling intervals

When to Use Webhooks

Ideal Scenarios for Webhooks

• Real-time requirements: When immediate notification is crucial
• High-volume environments: When polling would be inefficient
• Event-driven architectures: When your system is designed around events
• Integration workflows: When actions need to trigger other systems

Consider Polling Instead When

• Simple use cases: When occasional delays are acceptable
• Firewall restrictions: When your infrastructure can't receive external requests
• Development simplicity: When webhook complexity isn't worth the benefits
• Backup mechanisms: As a fallback when webhook delivery fails

Common Use Cases

Document Lifecycle Management

• CRM synchronization: Update opportunity status when documents are signed
• Workflow automation: Trigger next steps when documents are completed
• Notification systems: Alert users when documents need attention

Business Process Integration

• Invoice processing: Generate invoices when quotes are approved
• Contract management: Archive completed contracts to document management systems
• Compliance tracking: Log document actions for audit trails

Real-Time Dashboards

• Status monitoring: Display real-time document progress
• Analytics updates: Track completion rates and processing times
• Alert systems: Notify managers of urgent document actions

Architecture and Design Considerations

Reliability Design

Idempotency: Design your webhook handler to safely process the same notification more than once, as automatic and manual retries may occur. Each delivery includes an X-PandaDoc-Webhook-Event-Id header: a stable UUID for that delivery across retries, and a distinct value when one underlying change fans out into multiple webhook event types. Use that header as your de-duplication key rather than assuming the payload alone uniquely identifies a delivery. For the header specification, see Webhook Events Reference. For implementation steps, see How to Deduplicate Webhook Deliveries.

Error Handling: Implement proper error handling and logging to diagnose issues when webhooks fail.

Graceful Degradation: Have fallback mechanisms (like periodic polling) in case webhook delivery fails.

Security Implications

Authentication: Always verify webhook signatures to ensure requests are from PandaDoc.

Authorization: Implement proper access controls for webhook endpoints.

Data Sensitivity: Consider what data is included in webhook payloads and handle accordingly.

Performance Considerations

Response Time: Webhook handlers must respond within 20 seconds or the request will timeout.

Asynchronous Processing: For heavy processing, acknowledge receipt immediately and process asynchronously.

Scaling: Design handlers to handle multiple concurrent webhook deliveries.

Limitations and Constraints

Technical Limits

• Maximum subscriptions: 300 per workspace
• HTTPS requirement: All webhook endpoints must use SSL
• Timeout limits: 5-second connection timeout, 20-second read timeout
• Payload format: Always delivered as JSON arrays

Operational Considerations

• Retry behavior: 3 automatic retries before manual intervention required
• IP restrictions: Must accept requests from PandaDoc's IP ranges

Why Subscriptions Are Deactivated

PandaDoc deactivates webhook subscriptions for two different reasons, which serve different purposes:

Immediate deactivation via HTTP 410 (Gone)

HTTP 410 is treated as an intentional signal that the endpoint no longer wants webhook deliveries. When your endpoint returns 410 Gone, PandaDoc deactivates that subscription immediately and stops sending further events. This follows the HTTP convention that a 410 response means the resource is permanently unavailable and should not be requested again.

Use 410 when you deliberately want to stop receiving webhooks for a subscription (for example, the callback URL has been retired). Do not return 410 for temporary failures—those should use other 4xx/5xx codes so the subscription can recover when your endpoint is healthy again.

Soft deactivation after sustained failures

If a subscription delivers only unsuccessful responses for 7 days—HTTP status codes of 400 or higher, or transport-level failures such as timeouts and connection errors—and has no successful deliveries (HTTP status below 400) in that window, PandaDoc deactivates it. A single successful response in the trailing 7-day window keeps the subscription active.

This protects both sides: PandaDoc avoids repeatedly calling dead or misconfigured endpoints, and workspace owners are prompted to fix or remove broken subscriptions rather than silently accumulating failures.

For the exact status-code rules and response requirements, see Webhook Events Reference. For what to do when a subscription is deactivated, see How to Debug and Monitor Webhooks.

Best Practices

Design Principles

1. Keep handlers simple: Acknowledge quickly, process asynchronously
2. Implement proper logging: Track all webhook events for debugging
3. Use database transactions: Ensure data consistency when processing events
4. Design for retries: Handle duplicate deliveries with X-PandaDoc-Webhook-Event-Id
5. Monitor proactively: Set up alerts for delivery failures
6. Choose status codes carefully: Return a status below 400 on success; reserve HTTP 410 for permanent unsubscribe only

Monitoring and Maintenance

1. Monitor delivery success: Track webhook delivery rates and failures
2. Set up alerting: Get notified when webhooks consistently fail
3. Regular testing: Periodically test webhook functionality
4. Documentation: Keep webhook behavior documented for team members

Related

• How to Set Up Webhook Notifications - Implementation guide
• How to Deduplicate Webhook Deliveries - Idempotent processing with event IDs
• How to Debug and Monitor Webhooks - Troubleshooting and monitoring
• How to Verify Webhook Authenticity - Security implementation
• Webhook Events Reference - Technical specifications