How to Debug and Monitor Webhooks

Problem

Your webhook integration is experiencing delivery failures, missed events, or other issues that require troubleshooting and ongoing monitoring.

Prerequisites

• Active webhook subscription (see How to Set Up Webhook Notifications)
• Access to PandaDoc Developer Dashboard
• Access to your webhook endpoint logs

Common Problems and Solutions

Problem: Webhooks Not Being Delivered

Symptoms: No webhook events appear in your application logs, but events are occurring in PandaDoc.

Solution:

1. Check webhook history:

   • Navigate to Webhooks History tab
   • Verify delivery attempts are being made
   • Check HTTP response codes

2. Verify webhook subscription:

   • Confirm subscription is active (not deactivated)
   • Check the endpoint URL is correct
   • Verify events are configured for the subscription

3. Test endpoint accessibility:

   • Ensure endpoint uses HTTPS (required)
   • Test endpoint responds to POST requests
   • Verify firewall allows inbound requests

Problem: Webhooks Failing with HTTP Errors

Symptoms: Webhook history shows 4xx or 5xx error responses.

Solution:

1. For 4xx errors (client errors):

   • Check your endpoint returns HTTP 200 for successful processing
   • Verify endpoint can handle JSON array payloads
   • Ensure endpoint processes requests within 20 seconds

2. For 5xx errors (server errors):

   • Check your server logs for application errors
   • Verify adequate server resources (CPU, memory)
   • Test endpoint with sample webhook payload

3. For timeout errors:

   • Optimize endpoint response time (must respond within 20 seconds)
   • Acknowledge webhook immediately, process asynchronously
   • Check for database connection issues

Problem: Webhook Subscription Deactivated

Symptoms: Webhook subscription shows as inactive in Developer Dashboard.

Solution:

1. Understand deactivation triggers:

   • 7 days of continuous 4xx/5xx errors without successful responses
   • HTTP 410 response immediately deactivates webhook

2. Reactivate webhook:

   • Fix underlying endpoint issues first
   • Update webhook subscription settings
   • Monitor delivery success after reactivation

3. Prevent future deactivation:

   • Implement proper error handling
   • Set up monitoring and alerting
   • Test webhook endpoint regularly

Problem: Need to Manually Retry Failed Webhooks

Symptoms: Automatic retries exhausted, webhook delivery marked as failed.

Solution:

1. Access webhook history:

   • Navigate to Webhooks History tab
   • Locate failed webhook delivery

2. Retry failed delivery:

   • Click "Retry" button next to failed delivery
   • Monitor retry attempt in delivery history

3. If retry fails again:
   • Check endpoint logs for specific error details
   • Verify endpoint can handle the specific event payload
   • Consider implementing fallback polling for missed events

Problem: Missing Webhook Events

Symptoms: Some events are being delivered, but specific events are missing.

Solution:

1. Check event configuration:

   • Verify correct events are selected in webhook subscription
   • Confirm events are actually occurring in PandaDoc

2. Review webhook history:

   • Check if events were sent but failed delivery
   • Look for patterns in successful vs failed events

3. Implement event tracking:

   • Log all received webhook events
   • Compare with expected events from business logic
   • Use webhook history to identify gaps

Problem: Webhook Performance Issues

Symptoms: Slow webhook processing, timeout errors, or high server load.

Solution:

1. Optimize endpoint response time:

   • Acknowledge webhook immediately (return HTTP 200)
   • Process webhook payload asynchronously
   • Use database transactions for consistency

2. Monitor webhook load:

   • Track webhook frequency and volume
   • Monitor server resources during peak webhook delivery
   • Set up alerts for high error rates

3. Implement proper error handling:

   • Return appropriate HTTP status codes
   • Log errors with sufficient detail for debugging
   • Implement circuit breaker patterns if needed

Monitoring and Maintenance

Access Webhook History

To monitor webhook delivery:

1. Navigate to Webhooks History tab
2. Review delivery logs showing:
   • Event timestamps
   • HTTP response codes
   • Delivery status (success/failure)
   • Error messages
   • Retry attempts

Related

• How to Set Up Webhook Notifications - Initial webhook configuration
• How to Verify Webhook Authenticity - Security implementation
• Webhook Events Reference - Technical specifications
• Understanding Webhooks - Concepts and architecture