Webhook listener

Webhooks are the most efficient method to be notified of state 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 a process that listens for HTTP POST actions at a particular URL that 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.

Give your webhook a friendly name that you will remember and add your listener URL in the Webhook Endpoint URL field. At the very least for this exercise you should check “Document state changed” under the “Subscribe to events” section, although you may wish to take advantage of other features offered in the webhook configuration that are described outside the scope of this recipe. Save your changes when you are finished.

When your document changes status you’ll get a postback from the webhook contains a “status” item

{
 …
  "status": "document.draft",
 …
}

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

Active polling

The other method of waiting for document status changes is to use the document ID from your document creation step and repeatedly
GET https://api.pandadoc.com/public/v1/documents/{id}
The block returned back will contain a “status” element. While the document is being processed this status will be “document.uploaded”

{
  …
  "status": "document.draft",
  …
}

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

📘

Note

Document processing times can vary and tend to follow a power law. Repeated use of the status endpoint can risk hitting your API rate limit. It’s recommended that you space out the timing of your active requests, such as adding an additional 1-second pause before retrying for every request that receives a “document.uploaded” response.