--- updatedAt: 2026-10-05T06:52:42.000Z agentTools: projectIndex: https://developers.pandadoc.com/llms.txt --- # Webhook Events Reference Complete reference of all webhook events, their payloads, and technical specifications. # 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](https://developers.pandadoc.com/reference/handledocumentstatechanged) | | `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](https://developers.pandadoc.com/reference/download-protected-document) endpoint. | [PDF Available](https://developers.pandadoc.com/reference/pdfofcompleteddocumentavailablefordownload) | | `document_updated` | The document has been returned to draft status. | [Document Updated](https://developers.pandadoc.com/reference/handledocumentupdated) | | `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](https://developers.pandadoc.com/reference/handlerecipientcompleteddocument) | | `document_deleted` | The document has been removed. | [Document Deleted](https://developers.pandadoc.com/reference/handledocumentdeleted) | | `document_creation_failed` | Document creation via API has failed. This event is triggered when the document does not move to "draft" status. | [Creation Failed](https://developers.pandadoc.com/reference/handledocumentcreationfailed) | | `document_section_added` | Indicates that the asynchronous creation of a section is complete. | [Section Added](https://developers.pandadoc.com/reference/handledocumentsectionadded) | | `quote_updated` | A user clicked the "Save" button after updating a quote in the Quote Builder within PandaDoc. | [Quote Updated](https://developers.pandadoc.com/reference/handlequoteupdated) | | `template_created` | A new template has been created. | [Template Created](https://developers.pandadoc.com/reference/handletemplatecreated) | | `template_updated` | An existing template has been updated. This includes changes to the name, roles, or the addition of sections.. | [Template Updated](https://developers.pandadoc.com/reference/handletemplateupdated) | | `template_deleted` | The template has been deleted. | [Template Deleted](https://developers.pandadoc.com/reference/handletemplatedeleted) | | `content_library_item_created` | A new CLI has been created. | [CLI Created](https://developers.pandadoc.com/reference/handlecontentlibraryitemcreated) | | `content_library_item_creation_failed` | CLI creation via API has failed. | [CLI Creation Failed](https://developers.pandadoc.com/reference/handlecontentlibraryitemcreationfailed) | ## Payload Structure ### Standard Payload Format All webhook payloads follow this array structure: ```json [ { "event": "event_name", "data": { // Event-specific data } } ] ``` ### Document Event Payload Most document events return data similar to the [Document Details](https://developers.pandadoc.com/reference/document-details) endpoint: ```json [ { "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": "test@pandadoc.com", "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": [ { "id": "8KAZvGRL3W4u44a4fyDoeH", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "recipient_type": "signer", "has_completed": true, "role": "Client", "roles": ["Client"], "type": "recipient", "shared_link": "https://app.pandadoc.com/document/15d4b481384b652a298530ddc7023bfc07a67d59" } ], "sent_by": { "id": "uHfzrB4Goai39ZkxDRLpMo", "email": "test@pandadoc.com", "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 ```json [ { "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) ### Request headers | Header | Value / format | Description | | ----------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Content-Type` | `application/json` | Payload media type | | `Accept` | `*/*` | Accepted response media types | | `User-Agent` | `PandaDoc Webhooks` | Identifies the PandaDoc webhook sender | | `X-PandaDoc-Webhook-Event-Id` | UUID (for example, `550e8400-e29b-41d4-a716-446655440000`) | Stable identifier for this webhook delivery. Identical when the same delivery is resent from the Developer Dashboard. Distinct when one underlying change produces multiple webhook event types (for example, `document_updated` and `document_state_changed`). Use for de-duplication. | For implementation steps, see [How to Deduplicate Webhook Deliveries](../docs/webhook-deduplication). ### Timeouts * **Connection timeout**: 5 seconds * **Read timeout**: 20 seconds ### Retry Mechanism * **Automatic retries**: None. Each delivery is one POST. Connection failures, timeouts, and non-2xx responses are not retried. * **Manual retry**: Developer Dashboard Webhooks History tab ### Response Requirements * **Recommended success response**: HTTP 200 * **Success for delivery tracking**: Any HTTP status code below 400 * **Failure for delivery tracking**: HTTP status code 400 or higher, or transport-level errors (timeout, connection failure) * **Processing time**: Must respond within 20 seconds ## Deactivation Conditions Webhook subscriptions are automatically deactivated in either of these cases: | Condition | Timing | Trigger | | --------------------------- | ------------ | ---------------------------------------------------------------------------------------- | | HTTP 410 Gone | Immediate | Endpoint responds with status `410` | | Sustained delivery failures | After 7 days | Only unsuccessful deliveries in the trailing 7-day window, with no successful deliveries | ### Immediate deactivation (HTTP 410) * Returning `410 Gone` deactivates the subscription on that delivery. * Use `410` only when the endpoint should permanently stop receiving webhooks for this subscription. ### Soft deactivation (7-day failure window) A subscription is soft-deactivated when, over the trailing 7 days: * It has at least one unsuccessful delivery (`response status >= 400`, or a transport error such as timeout/connection failure), and * It has no successful deliveries (`error` unset and `response status < 400`) A single successful response (status below 400) in that window prevents soft deactivation. ## 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) ## Related * [How to Set Up Webhook Notifications](../docs/webhook-setup) - Setup instructions * [How to Deduplicate Webhook Deliveries](../docs/webhook-deduplication) - Idempotent processing with event IDs * [How to Debug and Monitor Webhooks](../docs/webhook-debugging) - Troubleshooting and monitoring * [How to Verify Webhook Authenticity](../docs/webhook-verification) - Security implementation * [Understanding Webhooks](../docs/webhooks-concepts) - Concepts and use cases