PandaDoc Webhook Events

asyncapi: 2.6.0
info:
  title: PandaDoc Webhook Events
  description: >-
    The PandaDoc webhook system delivers real-time event notifications to
    registered subscriber endpoints when document lifecycle and platform
    events occur. PandaDoc sends HTTP POST requests containing JSON arrays
    of event objects to the target URL configured in a webhook subscription.
    Each event payload includes the trigger type and a data object describing
    the affected entity. Payloads are signed using HMAC-SHA256 with a
    per-subscription shared key, enabling receivers to verify authenticity
    before processing. Subscriptions can be configured to include optional
    payload extras such as fields, products, metadata, tokens, and pricing
    data alongside the base event information.
  version: '1.0'
  contact:
    name: PandaDoc API Support
    url: https://developers.pandadoc.com/docs/webhooks-concepts
  termsOfService: https://www.pandadoc.com/master-services-agreement/
externalDocs:
  description: PandaDoc Webhooks Documentation
  url: https://developers.pandadoc.com/docs/webhooks-concepts
servers:
  pandadoc:
    url: 'https://api.pandadoc.com'
    protocol: https
    description: >-
      PandaDoc sends webhook notifications as HTTP POST requests originating
      from the PandaDoc platform. Receiving endpoints must be publicly
      accessible HTTPS URLs registered via the Webhook Subscriptions API or
      the PandaDoc Developer Dashboard. The x-pd-signature header contains
      the HMAC-SHA256 signature for payload verification.
    security:
      - hmacSignature: []
channels:
  /webhook:
    description: >-
      The HTTPS endpoint on the subscriber's server that receives webhook
      notifications from PandaDoc. PandaDoc sends HTTP POST requests with
      JSON array payloads containing one or more event objects. The receiver
      must respond with a 2xx HTTP status code to acknowledge delivery.
      Payloads are signed with the subscription shared key via HMAC-SHA256
      delivered in the x-pd-signature request header.
    publish:
      operationId: receivePandaDocWebhookEvent
      summary: Receive a webhook event notification from PandaDoc
      description: >-
        PandaDoc sends this message to the subscriber's registered endpoint
        URL when a subscribed event occurs on the platform. The receiver
        should validate the x-pd-signature header using the subscription
        shared key before processing the payload. PandaDoc expects a 2xx
        response within its timeout window; failed deliveries are logged
        and can be reviewed via the Webhook Events API.
      message:
        oneOf:
          - $ref: '#/components/messages/DocumentStateChangedEvent'
          - $ref: '#/components/messages/RecipientCompletedEvent'
          - $ref: '#/components/messages/DocumentUpdatedEvent'
          - $ref: '#/components/messages/DocumentDeletedEvent'
          - $ref: '#/components/messages/DocumentCreationFailedEvent'
          - $ref: '#/components/messages/DocumentCompletedPdfReadyEvent'
          - $ref: '#/components/messages/DocumentSectionAddedEvent'
          - $ref: '#/components/messages/QuoteUpdatedEvent'
          - $ref: '#/components/messages/TemplateCreatedEvent'
          - $ref: '#/components/messages/TemplateUpdatedEvent'
          - $ref: '#/components/messages/TemplateDeletedEvent'
          - $ref: '#/components/messages/ContentLibraryItemCreatedEvent'
          - $ref: '#/components/messages/ContentLibraryItemCreationFailedEvent'
components:
  securitySchemes:
    hmacSignature:
      type: httpApiKey
      name: x-pd-signature
      in: header
      description: >-
        HMAC-SHA256 signature computed by signing the raw JSON request body
        with the webhook subscription's shared key. Recipients must compute
        the same HMAC-SHA256 signature of the raw request body using the
        shared key and compare it to the x-pd-signature header value to
        verify that the notification originated from PandaDoc. The shared
        key can be rotated via the Update Webhook Subscription Shared Key API.
  messages:
    DocumentStateChangedEvent:
      name: document_state_changed
      title: Document State Changed
      summary: >-
        Notification sent when a document transitions to a new lifecycle
        status such as sent, viewed, completed, declined, or voided.
      description: >-
        PandaDoc sends this event whenever a document moves between status
        values. Common transitions include draft to sent, sent to viewed,
        sent to completed, and sent to declined. The data payload includes
        full document metadata, recipient completion status, and optionally
        field values, pricing, metadata, and tokens if configured in the
        subscription.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body using the subscription
              shared key. Verify this value to confirm the notification
              originated from PandaDoc.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    RecipientCompletedEvent:
      name: recipient_completed
      title: Recipient Completed
      summary: >-
        Notification sent when an individual recipient completes all required
        actions on a document such as signing all assigned fields.
      description: >-
        PandaDoc sends this event each time a single recipient finishes
        their required actions on a document. This fires independently for
        each recipient and before the overall document_state_changed event
        that signals full completion. The data payload includes the document
        and recipient details.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    DocumentUpdatedEvent:
      name: document_updated
      title: Document Updated
      summary: >-
        Notification sent when a document's content or metadata is modified,
        such as when fields are updated or tokens are changed while the
        document is in draft.
      description: >-
        PandaDoc sends this event when a document is edited or its
        configuration changes. This includes field value updates, recipient
        changes, and content modifications made through the API or the
        PandaDoc editor. The data payload includes updated document metadata.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    DocumentDeletedEvent:
      name: document_deleted
      title: Document Deleted
      summary: >-
        Notification sent when a document is permanently deleted from the
        PandaDoc workspace.
      description: >-
        PandaDoc sends this event when a document is deleted via the API or
        the PandaDoc interface. The data payload includes the document
        identifier and basic metadata. After deletion, the document is no
        longer accessible via the API.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    DocumentCreationFailedEvent:
      name: document_creation_failed
      title: Document Creation Failed
      summary: >-
        Notification sent when asynchronous document creation fails, such as
        when a file upload or template generation encounters an error.
      description: >-
        PandaDoc sends this event when a document that was initiated but
        not yet in draft status encounters a processing error. This typically
        occurs when uploaded files cannot be processed or when template
        generation fails. The data payload includes the failed document
        identifier and error details.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    DocumentCompletedPdfReadyEvent:
      name: document_completed_pdf_ready
      title: Document Completed PDF Ready
      summary: >-
        Notification sent when the signed PDF for a completed document has
        finished generating and is ready to download.
      description: >-
        After a document reaches document.completed status, PandaDoc
        generates the final signed PDF asynchronously. This event fires when
        that PDF generation is complete and the document is available for
        download via the Download Document API. Listen for this event to
        trigger post-signature workflows that require the signed PDF.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    DocumentSectionAddedEvent:
      name: document_section_added
      title: Document Section Added
      summary: >-
        Notification sent when a new section is successfully added to a
        document bundle via asynchronous upload.
      description: >-
        PandaDoc sends this event when a file upload for a document section
        or bundle completes processing and the section has been appended to
        the document. The data payload includes the document and section
        identifiers.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    QuoteUpdatedEvent:
      name: quote_updated
      title: Quote Updated
      summary: >-
        Notification sent when pricing table or quote data within a document
        is updated.
      description: >-
        PandaDoc sends this event when a document's embedded quote or pricing
        table is modified. This includes price changes, quantity updates, or
        product additions made via the Quotes API or through the document
        editor. The data payload includes the document and quote identifiers.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/DocumentEventPayload'
    TemplateCreatedEvent:
      name: template_created
      title: Template Created
      summary: >-
        Notification sent when a new template is successfully created in the
        workspace.
      description: >-
        PandaDoc sends this event when a template is created via the API
        or the PandaDoc editor. The data payload includes the template
        identifier, name, and creation timestamp.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/TemplateEventPayload'
    TemplateUpdatedEvent:
      name: template_updated
      title: Template Updated
      summary: >-
        Notification sent when an existing template is modified.
      description: >-
        PandaDoc sends this event when a template's content, settings, roles,
        or fields are modified. The data payload includes the template
        identifier and modification timestamp.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/TemplateEventPayload'
    TemplateDeletedEvent:
      name: template_deleted
      title: Template Deleted
      summary: >-
        Notification sent when a template is permanently deleted from the
        workspace.
      description: >-
        PandaDoc sends this event when a template is deleted. The data
        payload includes the deleted template's identifier and name.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/TemplateEventPayload'
    ContentLibraryItemCreatedEvent:
      name: content_library_item_created
      title: Content Library Item Created
      summary: >-
        Notification sent when a content library item finishes processing
        and is ready for use in documents.
      description: >-
        PandaDoc sends this event after a content library item upload
        completes processing and the item is available to be appended to
        documents. The data payload includes the item identifier and name.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/ContentLibraryItemEventPayload'
    ContentLibraryItemCreationFailedEvent:
      name: content_library_item_creation_failed
      title: Content Library Item Creation Failed
      summary: >-
        Notification sent when a content library item upload fails during
        processing.
      description: >-
        PandaDoc sends this event when a content library item that was
        uploaded cannot be processed. The data payload includes the item
        identifier and error information.
      contentType: application/json
      headers:
        type: object
        properties:
          x-pd-signature:
            type: string
            description: HMAC-SHA256 signature of the request body.
      payload:
        $ref: '#/components/schemas/ContentLibraryItemEventPayload'
  schemas:
    WebhookEventEnvelope:
      type: array
      description: >-
        Webhook payloads are delivered as JSON arrays. Each array element
        is a single event object containing the event type and data payload.
      items:
        type: object
        required:
          - event
          - data
        properties:
          event:
            type: string
            description: >-
              The event trigger type that caused this notification.
            enum:
              - document_state_changed
              - recipient_completed
              - document_updated
              - document_deleted
              - document_creation_failed
              - document_completed_pdf_ready
              - document_section_added
              - quote_updated
              - template_created
              - template_updated
              - template_deleted
              - content_library_item_created
              - content_library_item_creation_failed
          data:
            type: object
            description: Event-specific data payload.
    DocumentEventPayload:
      type: array
      description: >-
        Payload for document lifecycle events. Delivered as a JSON array
        containing a single event object with document data.
      items:
        type: object
        required:
          - event
          - data
        properties:
          event:
            type: string
            description: Event trigger type.
            example: document_state_changed
          data:
            $ref: '#/components/schemas/DocumentEventData'
    DocumentEventData:
      type: object
      description: Document data included in document lifecycle event payloads.
      properties:
        id:
          type: string
          description: Unique identifier of the document.
          example: aahcZhiB6pKRbjagoZrrrr
        name:
          type: string
          description: Display name of the document.
          example: Service Agreement
        date_created:
          type: string
          format: date-time
          description: Timestamp when the document was created.
        date_modified:
          type: string
          format: date-time
          description: Timestamp when the document was last modified.
        expiration_date:
          type: string
          format: date-time
          nullable: true
          description: Expiration timestamp if set on the document.
        status:
          type: string
          description: Current lifecycle status of the document.
          enum:
            - document.draft
            - document.sent
            - document.completed
            - document.uploaded
            - document.error
            - document.viewed
            - document.waiting_approval
            - document.approved
            - document.rejected
            - document.waiting_pay
            - document.paid
            - document.voided
            - document.declined
            - document.external_review
          example: document.completed
        tags:
          type: array
          description: Tags applied to the document.
          items:
            type: string
        created_by:
          $ref: '#/components/schemas/UserReference'
        sent_by:
          allOf:
            - $ref: '#/components/schemas/UserReference'
          nullable: true
          description: The user who sent the document, or null if not yet sent.
        recipients:
          type: array
          description: Recipients assigned to the document and their completion status.
          items:
            $ref: '#/components/schemas/RecipientReference'
        template:
          type: object
          nullable: true
          description: Template this document was created from, if any.
          properties:
            id:
              type: string
              description: Template identifier.
            name:
              type: string
              description: Template display name.
        grand_total:
          type: object
          nullable: true
          description: Total monetary value from pricing tables.
          properties:
            amount:
              type: string
              description: Numeric string of the total amount.
            currency:
              type: string
              description: ISO 4217 currency code.
        version:
          type: string
          nullable: true
          description: Document version string.
        linked_objects:
          type: array
          description: CRM or external objects linked to this document.
          items:
            type: object
    UserReference:
      type: object
      description: Reference to a PandaDoc user.
      properties:
        id:
          type: string
          description: User identifier.
        email:
          type: string
          format: email
          description: User email address.
        first_name:
          type: string
          description: User first name.
        last_name:
          type: string
          description: User last name.
        avatar:
          type: string
          nullable: true
          description: URL of the user's avatar image.
        membership_id:
          type: string
          description: Workspace membership identifier.
    RecipientReference:
      type: object
      description: Reference to a document recipient with their completion status.
      properties:
        type:
          type: string
          description: Participant type in the document.
          example: recipient
        id:
          type: string
          description: Recipient identifier.
        first_name:
          type: string
          description: Recipient first name.
        last_name:
          type: string
          description: Recipient last name.
        email:
          type: string
          format: email
          description: Recipient email address.
        phone:
          type: string
          description: Recipient phone number.
        recipient_type:
          type: string
          description: Role type of the recipient.
          enum:
            - SIGNER
            - CC
            - APPROVER
        has_completed:
          type: boolean
          description: Whether this recipient has completed all required actions.
        role:
          type: string
          description: Role name mapping the recipient to document fields.
        roles:
          type: array
          description: All roles assigned to this recipient.
          items:
            type: string
        signing_order:
          type: integer
          nullable: true
          description: Position in the signing order sequence.
        contact_id:
          type: string
          nullable: true
          description: Associated contact record identifier.
        shared_link:
          type: string
          description: Public signing link for this recipient.
    TemplateEventPayload:
      type: array
      description: >-
        Payload for template lifecycle events. Delivered as a JSON array
        containing a single event object with template data.
      items:
        type: object
        required:
          - event
          - data
        properties:
          event:
            type: string
            description: Event trigger type.
            example: template_updated
          data:
            $ref: '#/components/schemas/TemplateEventData'
    TemplateEventData:
      type: object
      description: Template data included in template lifecycle event payloads.
      properties:
        id:
          type: string
          description: Unique identifier of the template.
        name:
          type: string
          description: Display name of the template.
        date_created:
          type: string
          format: date-time
          description: Timestamp when the template was created.
        date_modified:
          type: string
          format: date-time
          description: Timestamp when the template was last modified.
        tags:
          type: array
          description: Tags applied to the template.
          items:
            type: string
    ContentLibraryItemEventPayload:
      type: array
      description: >-
        Payload for content library item events. Delivered as a JSON array
        containing a single event object with content library item data.
      items:
        type: object
        required:
          - event
          - data
        properties:
          event:
            type: string
            description: Event trigger type.
            example: content_library_item_created
          data:
            $ref: '#/components/schemas/ContentLibraryItemEventData'
    ContentLibraryItemEventData:
      type: object
      description: Content library item data in event payloads.
      properties:
        id:
          type: string
          description: Unique identifier of the content library item.
        name:
          type: string
          description: Display name of the content library item.
        date_created:
          type: string
          format: date-time
          description: Timestamp when the item was created.
        status:
          type: string
          description: Processing status of the content library item.
          enum:
            - pending
            - processed
            - error