Update to version 4.2.0 on 2026-10-29

- **BREAKING CHANGE**: list_templates returns a shorter `TemplateSummary`: a template's name, description, type, folder
  (`parent_folder_id`, `path`), latest published version, whether it's `ready`, and its PDF's file name, state, error
  and page count (`document`, a `TemplateDocumentSummary`). get_template returns its settings and the rest.
- **BREAKING CHANGE**: list_submissions and list_template_submissions return `SubmissionSummary` instead of
  `Submission`: without signature requests and uploads, with `data` only when you pass `include_data` (as before), and
  with `files` only when you pass the new `include_files` (without the links to page images). get_submission returns the
  whole submission.
- New: the template webhook events (version 4) send the whole template, as get_template returns it, without its
  `embed_edit_token`. They sent the settings without the rest.
- New: list_submissions and list_template_submissions take a `state` filter: one state, such as `invalid_data` or
  `error`.
- New: get_template_model_code takes `just_types`, for the types alone, without the code that converts and checks JSON
  (TypeScript, Ruby, Python, Java, C#, Elixir and Go: JavaScript and PHP code is the same either way).
- New: create_submission, create_submission_batch and create_combined_pdf take an `Idempotency-Key` header. A request
  repeated with the same key within 24 hours returns the first response and creates nothing. The same key with a
  different request is a 422, and a repeat while the first request is still running is a 409.
- New: create_template_preview and get_template_preview fill an HTML or PDF template's draft (or a published version)
  with your data and return PNG images of its pages, not a PDF, so you can check how it prints before you publish it or
  send live data. A preview creates no submission and uses no credits. Get the preview until its `state` is
  `processed`. Previews are watermarked like test PDFs.
- New: HTML templates' `html_escape_data` setting HTML-escapes the values they print (`{{ value }}`). It's on for new
  templates and off for existing ones; `{{ value | raw }}` prints a value as it is.
- New: `docspring.verify_webhook_signature(payload, signature_header, secret)` (the payload as `str` or `bytes`) checks
  a webhook request's `X-DocSpring-Signature` header. Pass it the request body exactly as it was received. It returns
  true or false, accepts any `v1` that matches and rejects a timestamp more than 5 minutes old (`tolerance=` for another
  tolerance).
- publish_template_version answers 409 when the draft hasn't changed since the latest published version, instead of
  publishing a copy of it (code `conflict`). A template's first publish always works.
- Every operation documents the 429 rate limit response (with `Retry-After`), and the creates that the sync hosts wait
  for document their 504 (the record was saved: get it by the ID in the error).
- Every optional field takes `null` in a submission's `data`, whatever its type, so model code that writes missing
  values as null works. A null checkbox or group of fields (an object or a list) gets its defaults, as a missing key
  does, and a null text, number, date, image or signature field prints blank, as before. Null in a required field is
  still an error.
- Template and webhook names can be up to 512 characters, up from 255.

Author: ndbroadbent

.openapi-generator/FILES

@@ -26,6 +26,7 @@ docs/CreateSignatureRequestEventRequest.md
 docs/CreateSignatureRequestTokenRequest.md
 docs/CreateSubmissionBatchRequest.md
 docs/CreateSubmissionRequest.md
+docs/CreateTemplatePreviewRequest.md
 docs/CreateTemplateRequest.md
 docs/CreateWebhookRequest.md
 docs/CustomFile.md
@@ -107,6 +108,7 @@ docs/SubmissionList.md
 docs/SubmissionSource.md
 docs/SubmissionSourcePdf.md
 docs/SubmissionState.md
+docs/SubmissionSummary.md
 docs/SubmissionValidation.md
 docs/Template.md
 docs/TemplateActor.md
@@ -117,6 +119,7 @@ docs/TemplateDiff.md
 docs/TemplateDiffSummary.md
 docs/TemplateDocument.md
 docs/TemplateDocumentState.md
+docs/TemplateDocumentSummary.md
 docs/TemplateFieldChange.md
 docs/TemplateFieldChanges.md
 docs/TemplateFieldDependency.md
@@ -137,6 +140,8 @@ docs/TemplatePageFieldsStatus.md
 docs/TemplatePageImageStatus.md
 docs/TemplatePageImages.md
 docs/TemplatePageProcessingStatus.md
+docs/TemplatePreview.md
+docs/TemplatePreviewState.md
 docs/TemplateSourcePdf.md
 docs/TemplateSummary.md
 docs/TemplateSummaryList.md
@@ -190,6 +195,7 @@ docspring/models/create_signature_request_event_request.py
 docspring/models/create_signature_request_token_request.py
 docspring/models/create_submission_batch_request.py
 docspring/models/create_submission_request.py
+docspring/models/create_template_preview_request.py
 docspring/models/create_template_request.py
 docspring/models/create_webhook_request.py
 docspring/models/custom_file.py
@@ -271,6 +277,7 @@ docspring/models/submission_list.py
 docspring/models/submission_source.py
 docspring/models/submission_source_pdf.py
 docspring/models/submission_state.py
+docspring/models/submission_summary.py
 docspring/models/submission_validation.py
 docspring/models/template.py
 docspring/models/template_actor.py
@@ -281,6 +288,7 @@ docspring/models/template_diff.py
 docspring/models/template_diff_summary.py
 docspring/models/template_document.py
 docspring/models/template_document_state.py
+docspring/models/template_document_summary.py
 docspring/models/template_field_change.py
 docspring/models/template_field_changes.py
 docspring/models/template_field_dependency.py
@@ -301,6 +309,8 @@ docspring/models/template_page_fields_status.py
 docspring/models/template_page_image_status.py
 docspring/models/template_page_images.py
 docspring/models/template_page_processing_status.py
+docspring/models/template_preview.py
+docspring/models/template_preview_state.py
 docspring/models/template_source_pdf.py
 docspring/models/template_summary.py
 docspring/models/template_summary_list.py
@@ -356,6 +366,7 @@ test/test_create_signature_request_event_request.py
 test/test_create_signature_request_token_request.py
 test/test_create_submission_batch_request.py
 test/test_create_submission_request.py
+test/test_create_template_preview_request.py
 test/test_create_template_request.py
 test/test_create_webhook_request.py
 test/test_custom_file.py
@@ -437,6 +448,7 @@ test/test_submission_list.py
 test/test_submission_source.py
 test/test_submission_source_pdf.py
 test/test_submission_state.py
+test/test_submission_summary.py
 test/test_submission_validation.py
 test/test_template.py
 test/test_template_actor.py
@@ -447,6 +459,7 @@ test/test_template_diff.py
 test/test_template_diff_summary.py
 test/test_template_document.py
 test/test_template_document_state.py
+test/test_template_document_summary.py
 test/test_template_field_change.py
 test/test_template_field_changes.py
 test/test_template_field_dependency.py
@@ -467,6 +480,8 @@ test/test_template_page_fields_status.py
 test/test_template_page_image_status.py
 test/test_template_page_images.py
 test/test_template_page_processing_status.py
+test/test_template_preview.py
+test/test_template_preview_state.py
 test/test_template_source_pdf.py
 test/test_template_summary.py
 test/test_template_summary_list.py

AGENTS.md

@@ -69,8 +69,9 @@ keeps it.
   (https://docspring.com/docs/webhooks/overview/). A webhook created with API v2 sends events in API v2's format
   (version 4).
 - Verify each request's `X-DocSpring-Signature` header before acting on it: an HMAC-SHA256 of `{t}.{raw body}` with the
-  webhook's signing secret, computed over the raw body exactly as received
-  (https://docspring.com/docs/webhooks/verifying-signatures/).
+  webhook's signing secret, where `t` must be within 5 minutes
+  (https://docspring.com/docs/webhooks/verifying-signatures/). Pass the raw body exactly as received, not parsed JSON,
+  to `docspring.verify_webhook_signature(payload, signature_header, secret)`, which returns true or false.
 - No webhook is sent when a submission starts waiting for credits.
 
 ## Signature requests

CHANGELOG.md

@@ -1,3 +1,41 @@
+### 4.2.0 [October 29, 2026]
+
+- **BREAKING CHANGE**: list_templates returns a shorter `TemplateSummary`: a template's name, description, type, folder
+  (`parent_folder_id`, `path`), latest published version, whether it's `ready`, and its PDF's file name, state, error
+  and page count (`document`, a `TemplateDocumentSummary`). get_template returns its settings and the rest.
+- **BREAKING CHANGE**: list_submissions and list_template_submissions return `SubmissionSummary` instead of
+  `Submission`: without signature requests and uploads, with `data` only when you pass `include_data` (as before), and
+  with `files` only when you pass the new `include_files` (without the links to page images). get_submission returns the
+  whole submission.
+- New: the template webhook events (version 4) send the whole template, as get_template returns it, without its
+  `embed_edit_token`. They sent the settings without the rest.
+- New: list_submissions and list_template_submissions take a `state` filter: one state, such as `invalid_data` or
+  `error`.
+- New: get_template_model_code takes `just_types`, for the types alone, without the code that converts and checks JSON
+  (TypeScript, Ruby, Python, Java, C#, Elixir and Go: JavaScript and PHP code is the same either way).
+- New: create_submission, create_submission_batch and create_combined_pdf take an `Idempotency-Key` header. A request
+  repeated with the same key within 24 hours returns the first response and creates nothing. The same key with a
+  different request is a 422, and a repeat while the first request is still running is a 409.
+- New: create_template_preview and get_template_preview fill an HTML or PDF template's draft (or a published version)
+  with your data and return PNG images of its pages, not a PDF, so you can check how it prints before you publish it or
+  send live data. A preview creates no submission and uses no credits. Get the preview until its `state` is
+  `processed`. Previews are watermarked like test PDFs.
+- New: HTML templates' `html_escape_data` setting HTML-escapes the values they print (`{{ value }}`). It's on for new
+  templates and off for existing ones; `{{ value | raw }}` prints a value as it is.
+- New: `docspring.verify_webhook_signature(payload, signature_header, secret)` (the payload as `str` or `bytes`) checks
+  a webhook request's `X-DocSpring-Signature` header. Pass it the request body exactly as it was received. It returns
+  true or false, accepts any `v1` that matches and rejects a timestamp more than 5 minutes old (`tolerance=` for another
+  tolerance).
+- publish_template_version answers 409 when the draft hasn't changed since the latest published version, instead of
+  publishing a copy of it (code `conflict`). A template's first publish always works.
+- Every operation documents the 429 rate limit response (with `Retry-After`), and the creates that the sync hosts wait
+  for document their 504 (the record was saved: get it by the ID in the error).
+- Every optional field takes `null` in a submission's `data`, whatever its type, so model code that writes missing
+  values as null works. A null checkbox or group of fields (an object or a list) gets its defaults, as a missing key
+  does, and a null text, number, date, image or signature field prints blank, as before. Null in a required field is
+  still an error.
+- Template and webhook names can be up to 512 characters, up from 255.
+
 ### 4.1.0 [October 27, 2026]
 
 - New: list_template_fields, add_template_fields, update_template_fields, remove_template_fields and

README.md

@@ -9,7 +9,7 @@ templates with your data, generates PDFs from HTML templates, combines PDFs and
 The code in this repository is generated from DocSpring's OpenAPI spec ([About this SDK](#about-this-sdk)). Issues and
 pull requests are welcome.
 
-Version 4.1.0. Requires Python >=3.10.
+Version 4.2.0. Requires Python >=3.10.
 
 ## Install and configure
 
@@ -90,6 +90,7 @@ Python code for every method.
 | [`create_submission`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#create_submission) | Generate a PDF |
 | [`create_submission_batch`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#create_submission_batch) | Generate PDFs in a batch |
 | [`create_template`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#create_template) | Create a template |
+| [`create_template_preview`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#create_template_preview) | Preview a template with data |
 | [`create_webhook`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#create_webhook) | Create a webhook |
 | [`delete_custom_file`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#delete_custom_file) | Delete a custom file |
 | [`delete_folder`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#delete_folder) | Delete a folder |
@@ -110,6 +111,7 @@ Python code for every method.
 | [`get_template_diff`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_template_diff) | Compare a version of a template with the one before it |
 | [`get_template_model_code`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_template_model_code) | Generate typed code for a template's submission data |
 | [`get_template_page_images`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_template_page_images) | Get images of a template's pages |
+| [`get_template_preview`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_template_preview) | Get a template preview |
 | [`get_template_schema`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_template_schema) | Get the JSON Schema of a template's submission data |
 | [`get_webhook`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#get_webhook) | Get a webhook |
 | [`list_combined_pdfs`](https://github.com/DocSpring/docspring-python/blob/main/docs/Client.md#list_combined_pdfs) | List combined PDFs |
@@ -169,6 +171,7 @@ The fork changes the Python generator:
 On top of the generated code, we add:
 
 - A client constructor that reads your credentials, region and host from the environment.
+- `docspring.verify_webhook_signature(payload, signature_header, secret)` checks a webhook request's `X-DocSpring-Signature` header, with `tolerance` and `now` keyword arguments.
 
 Each release regenerates every file, so a change made only here would be lost in the next one. Issues and pull
 requests are welcome all the same: [open an issue](https://github.com/DocSpring/docspring-python/issues) or a pull request, or email