Webhook Events Reference

Overview

This reference provides technical specifications for all webhook events, payload formats, and delivery mechanisms.

Events

The following table lists all available webhook events with their descriptions and links to detailed specifications including payload schemas and examples.

Event Name	Event Description	Specification
`document_state_changed`	The document's status has changed. Use this event to track when a document moves to draft (indicating that its asynchronous creation is complete), or when it is viewed, completed, paid, etc.	Document State Changed
`document_completed_pdf_ready`	The document has been completed, and a PDF has been generated and saved to our e-vault. Use this event to download the PDF of the completed document via the Download Protected Document endpoint.	PDF Available
`document_updated`	The document has been returned to draft status.	Document Updated
`recipient_completed`	A recipient has completed the document. JSON payload additionally contains `action_by` and `action_date` fields, providing information on who completed the document and when. This event does not indicate that the document itself is completed.	Recipient Completed
`document_deleted`	The document has been removed.	Document Deleted
`document_creation_failed`	Document creation via API has failed. This event is triggered when the document does not move to "draft" status.	Creation Failed
`document_section_added`	Indicates that the asynchronous creation of a section is complete.	Section Added
`quote_updated`	A user clicked the "Save" button after updating a quote in the Quote Builder within PandaDoc.	Quote Updated
`template_created`	A new template has been created.	Template Created
`template_updated`	An existing template has been updated. This includes changes to the name, roles, or the addition of sections..	Template Updated
`template_deleted`	The template has been deleted.	Template Deleted
`content_library_item_created`	A new CLI has been created.	CLI Created
`content_library_item_creation_failed`	CLI creation via API has failed.	CLI Creation Failed

Payload Structure

Standard Payload Format

All webhook payloads follow this array structure:

[
  {
    "event": "event_name",
    "data": {
      // Event-specific data
    }
  }
]

Document Event Payload

Most document events return data similar to the Document Details endpoint:

[
  {
    "event": "document_state_changed",
    "data": {
      "id": "eHCjisfzWydzJnbqnBbvAj",
      "name": "My document for webhooks testing",
      "date_created": "2024-03-18T15:55:03.090372Z",
      "date_modified": "2024-03-18T16:26:46.286951Z",
      "expiration_date": "2024-05-17T16:26:45.583270Z",
      "autonumbering_sequence_name": null,
      "created_by": {
        "id": "uHfzrB4Goai39ZkxDRLpMo",
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "Test",
        "avatar": null,
        "membership_id": "vk5aRcJG4RTd2J83wNGFT5"
      },
      "metadata": {},
      "tokens": [],
      "fields": [],
      "products": [],
      "pricing": {
        "tables": [],
        "quotes": [],
        "merge_rules": []
      },
      "total": "130",
      "tags": [],
      "status": "document.completed",
      "recipients": [],
      "sent_by": {
        "id": "uHfzrB4Goai39ZkxDRLpMo",
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "Test",
        "avatar": null,
        "membership_id": "vk5aRcJG4RTd2J83wNGFT5"
      },
      "grand_total": {
        "amount": "130.00",
        "currency": "USD"
      },
      "template": {
        "id": "A9VkDBdjqn3HvRx7zyME3n",
        "name": "My template for webhooks testing"
      },
      "version": "2",
      "linked_objects": []
    }
  }
]

Document Creation Failed Payload

[
  {
    "event": "document_creation_failed",
    "data": {
      "id": "ptSNky6J4Q8yDh3QKwa7fZ",
      "error": {
        "type": "validation_error",
        "detail": "Role for form field with name='userName' is not provided in payload"
      }
    }
  }
]

Payload Configuration

Default Fields

Always included in document webhooks:

Basic document information
recipients array

Optional Fields

Configure during webhook setup:

fields - Form fields and their values
tokens - Document tokens
products - Product information
pricing - Pricing tables and quotes

Delivery Specifications

Delivery Method

HTTP Method: POST
Content-Type: application/json
Format: JSON array (may contain multiple events)

Timeouts

Connection timeout: 5 seconds
Read timeout: 20 seconds

Retry Mechanism

Automatic retries: 3 attempts
Manual retry: Available via Developer Dashboard
Retry schedule: Exponential backoff

Response Requirements

Success response: HTTP 200 status code
Processing time: Must respond within 20 seconds
Error handling: 4xx/5xx errors tracked for deactivation

Deactivation Conditions

Webhook subscriptions are automatically deactivated when:

Server responds with HTTP 410 (Gone) status
Continuous 4xx/5xx errors for 7 days without successful responses

Security

IP Allowlist

US Servers

52.12.31.116/32
52.37.240.175/32
35.167.41.246/32

EU Servers

3.76.175.239
18.192.96.161
18.158.79.41

Authentication

HMAC-SHA256 signature verification available
Shared key provided in Developer Dashboard
Signature sent as URL query parameter

Limits

Maximum subscriptions: 300 per workspace
Payload format: Array structure (supports multiple events)
Scope: Per-workspace (separate subscriptions required for multiple workspaces)

How to Set Up Webhook Notifications - Setup instructions
How to Debug and Monitor Webhooks - Troubleshooting and monitoring
How to Verify Webhook Authenticity - Security implementation
Understanding Webhooks - Concepts and use cases