API recipes: Listening for changes in document status

Avatar
Marya Maksimchuk
  • Updated

Availability: Enterprise

Method 1: Webhook listener

Webhooks are the most efficient method to be notified of status changes in a document. To take advantage of webhooks, however, you need to have a listener endpoint configured on your own server. This can be as simple as having a process that listens for HTTP POST actions at a particular URL you control, such as https://example.com/newWebhookEndpoint.

To create a new PandaDoc webhook, open https://app.pandadoc.com/a/#/api/configuration and use the “Create webhook” button in the Webhooks section.

mceclip0.png

Give your webhook a friendly name you’ll remember, then add your listener URL in the Webhook Endpoint URL field. We recommend checking “Document state changed” under the “Subscribe to events” section, although you may wish to take advantage of other features offered in the webhook configuration described outside the scope of these instructions. Once you’re finished, save your changes.mceclip1.png

When your document’s status changes, you’ll get a post back from the webhook containing a “status” item:

mceclip2.png

When the status changes to “document.draft,” you can send your document.

Method 2: Active polling

The other method of waiting for document status changes is to use the document ID from your document creation step and repeatedly add:

GET https://api.pandadoc.com/public/v1/documents/{id}

The block returned will contain a “status” element. While the document is being processed, this status will be “document.uploaded.”

mceclip4.png

When the status changes to “document.draft,” you can send your document.

Note:

Document processing times can vary and tend to follow a power law. Repeated use of the status endpoint increases your risk of hitting your API rate limit. We recommend you separate the timing of your active requests by adding a one-second pause before retrying every request that receives a “document.uploaded” response.

Related articles