How to Set Up Webhook Notifications

Problem

You need to receive real-time notifications when documents change status, templates are updated, or other events occur in your PandaDoc workspace, rather than continuously polling the API for updates.

Prerequisites

• Active PandaDoc API account with access token
• A publicly accessible HTTPS endpoint to receive webhook notifications
• Basic understanding of HTTP callbacks and JSON processing

📘

Testing Webhook locally

We only support SSL (https://) connections, which may present challenges when testing webhooks locally.
A possible solution is to use tools like ngrok, localtunnel, Cloudflare Tunnel, or any other service that can proxy requests to your local address and provide a globally accessible HTTPS URL.

Solution

Step 1: Choose Your Setup Method

You can create webhook subscriptions using either:

1. Developer Dashboard UI: https://app.pandadoc.com/a/#/api-dashboard/configuration
2. API endpoint: Create Webhooks Subscription

Step 2: Configure Your Webhook Endpoint

Prepare your server endpoint to:

• Accept POST requests with JSON payload
• Return HTTP 200 status for successful processing
• Handle array format (webhooks may contain multiple events)
• Process requests within 20 seconds to avoid timeout

Step 3: Create Your Webhook Subscription

Choose one of the following methods based on your selection in Step 1:

Option A: Using Developer Dashboard UI

1. Navigate to the Developer Dashboard
2. Go to Webhooks section
3. Click "Add Webhook"
4. Enter your HTTPS endpoint URL
5. Select events you want to receive
6. Configure additional data fields (fields, tokens, products, pricing)
7. Save the configuration

Option B: Using API Endpoint

Make a POST request to the Create Webhooks Subscription endpoint:

curl -X POST "https://api.pandadoc.com/public/v1/webhook-subscriptions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "url": "https://your-domain.com/webhook-handler",
    "triggers": ["document_state_changed", "document_completed"],
    "payload": ["fields", "products"],
    "active": true
  }'

📝

Note: This example is synchronized with the Create Webhooks Subscription API reference. For the most up-to-date request schema and available parameters, always refer to the API reference documentation.

Step 4: Handle Multiple Workspaces (If Needed)

If you work with multiple workspaces:

• Create separate subscriptions for each workspace
• Consider using workspace_id as a URL parameter: https://your-domain.com/webhook-handler?workspace_id={workspace_id}
• Each subscription only receives events from its specific workspace

Verification

To confirm your webhook is working:

1. Check the webhook appears in your Developer Dashboard OR verify via API:

   Bash

   curl -X GET "https://api.pandadoc.com/public/v1/webhook-subscriptions" \
     -H "Authorization: Bearer YOUR_API_TOKEN"

   This returns all your webhook subscriptions with their status and configuration.

2. Trigger a test event (e.g., change document status)

3. Verify your endpoint receives the webhook payload

4. Check webhook delivery status in the Webhooks History tab

Troubleshooting

If you encounter issues with webhook delivery:

1. Check basic requirements:

   • Endpoint uses HTTPS (required)
   • Returns HTTP 200 status
   • Responds within 20 seconds
   • Webhook subscription is active

2. For detailed troubleshooting: See How to Debug and Monitor Webhooks

Quick Retry

PandaDoc automatically retries failed webhooks 3 times. For manual retries or detailed debugging, use the Webhooks History tab in Developer Dashboard.

Limits

• Maximum 300 webhook subscriptions per workspace
• Webhook payload delivered as array (may contain multiple events)
• Basic document information always included; additional fields configurable

Related

• How to Debug and Monitor Webhooks - Troubleshooting and monitoring
• How to Verify Webhook Authenticity - Secure your webhook endpoint
• Webhook Events Reference - Complete list of available events
• Understanding Webhooks - Concepts and architecture