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