Building a Reliable Document Creation Workflow

Creating and sending documents programmatically is a cornerstone of the PandaDoc API. To ensure a smooth and dependable automated process, it's crucial to correctly handle the asynchronous nature of document creation. When you send a request to create a document, PandaDoc begins a background process and immediately returns a document ID with an initial status of document.uploaded. The document is not ready to be sent until it transitions to the document.draft status.

This article outlines three distinct workflows to manage this asynchronous operation, catering to different levels of complexity and reliability needs.

Option 1: The Simple Approach - Polling Document Status

This is the most straightforward method to implement if you are new to the PandaDoc API or do not have the infrastructure to handle webhooks. It involves periodically checking the document's status until it is ready to be sent.

Workflow:

1. Create the Document: Make a POST request to the Create Document endpoint.
2. Poll for Status: After the initial request, begin polling the Document Status endpoint.
   • Wait for at least one second between polling requests to give the document time to process.
   • Continue to poll as long as the status remains document.uploaded.
3. Send the Document: Once the polling response shows the status as document.draft, you can then make a POST request to the Send Document endpoint to send it.

Don't forget to stop polling if you get the document.error status.

When to use this approach: This method is ideal for simpler applications or for developers who want a quick and easy implementation without the need for a dedicated webhook handling service. The downside of it is a limited scalability - if you create too many documents at the same time, you might hit a rate limits for requests.

Option 2: The Advanced Approach - Relying on Webhooks

For a more scalable and efficient workflow, you can utilize webhooks. This approach eliminates the need for continuous polling and allows your application to react to status changes.

Workflow:

1. Set up a Webhook Listener: Configure a public endpoint in your application that can receive POST requests from PandaDoc.
2. Subscribe to Events: In your PandaDoc developer settings, subscribe to the Document state changed webhook event.
3. Create the Document: Make a POST request to the Create Document endpoint.
4. Receive Webhook Notification: PandaDoc will automatically send a notification to your listener when the document status changes.
5. Send the Document: When your listener receives a webhook payload indicating the document status is now document.draft, trigger the call to the Send Document endpoint.

When to use this approach: This is the recommended approach for applications that require real-time notifications and want to avoid the overhead of constant polling. It is more scalable and efficient.

Option 3: The Most Robust Approach - Combining Webhooks and Polling

This hybrid approach provides the highest level of reliability by using webhooks as the primary notification mechanism while having a polling system as a fallback. This ensures that you can still process documents even in the rare case of a webhook delivery failure.

Workflow:

1. Implement the Webhook Workflow: Follow all the steps outlined in Option 2 for creating the document and listening for webhook notifications.
2. Create a Fallback Job: Develop a scheduled job (e.g., a cron job) that runs periodically (for instance, every 10-60 seconds, depending on your application needs).
3. Identify "Stuck" Documents: The job should query your database for documents that have been in the document.uploaded state for an unusually long time (e.g., more than 30 seconds).
4. Poll for Status: For each of these "stuck" documents, the job will call the Document Status endpoint to get the current status.
5. Send if Ready: If the polled status is document.draft, the job should then trigger the call to the Send Document endpoint.

When implementing this approach, account for a possibility of concurrently getting the same document update from webhook and polling.

When to use this approach: This comprehensive workflow is best for mission-critical applications where you need to ensure every document is sent successfully. It provides a safety net that accounts for potential points of failure in a distributed system.

By choosing the workflow that best fits your application's needs, you can build a resilient and reliable document creation and sending process with the PandaDoc API. For more in-depth information, please visit the official PandaDoc API Reference.