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 event multiple times, as retries may occur.

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

• Deactivation rules: Subscriptions deactivate after 7 days of errors
• Retry behavior: 3 automatic retries before manual intervention required
• IP restrictions: Must accept requests from PandaDoc's IP ranges

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 events gracefully
5. Monitor proactively: Set up alerts for delivery failures

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 Debug and Monitor Webhooks - Troubleshooting and monitoring
• How to Verify Webhook Authenticity - Security implementation
• Webhook Events Reference - Technical specifications