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.

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": [
        {
          "id": "8KAZvGRL3W4u44a4fyDoeH",
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "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": "[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)

Request headers

For implementation steps, see How to Deduplicate Webhook Deliveries.

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

• 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:

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 - Setup instructions
• How to Deduplicate Webhook Deliveries - Idempotent processing with event IDs
• How to Debug and Monitor Webhooks - Troubleshooting and monitoring
• How to Verify Webhook Authenticity - Security implementation
• Understanding Webhooks - Concepts and use cases